From c972ff79ed63d9958a26a1e1d1666d935818d346 Mon Sep 17 00:00:00 2001 From: Gordon Shotwell Date: Tue, 27 Feb 2024 16:20:49 -0400 Subject: [PATCH 1/6] Add Quarto Space docs --- docs/hub/_toctree.yml | 2 ++ docs/hub/spaces-sdks-docker-quarto.md | 24 ++++++++++++++++++++++++ 2 files changed, 26 insertions(+) create mode 100644 docs/hub/spaces-sdks-docker-quarto.md diff --git a/docs/hub/_toctree.yml b/docs/hub/_toctree.yml index 19d7ef3d1..a01d05c24 100644 --- a/docs/hub/_toctree.yml +++ b/docs/hub/_toctree.yml @@ -214,6 +214,8 @@ title: Livebook on Spaces - local: spaces-sdks-docker-shiny title: Shiny on Spaces + - local: spaces-sdks-docker-quarto + title: Quarto on Spaces - local: spaces-sdks-docker-zenml title: ZenML on Spaces - local: spaces-sdks-docker-panel diff --git a/docs/hub/spaces-sdks-docker-quarto.md b/docs/hub/spaces-sdks-docker-quarto.md new file mode 100644 index 000000000..afacc7d18 --- /dev/null +++ b/docs/hub/spaces-sdks-docker-quarto.md @@ -0,0 +1,24 @@ +# Quarto on Spaces + +Quarto is a powerful tool for creating reproducible scientific and technical documents. +With Quarto you can interleave markdown and code chunks to generate pdfs, websites, presentations and more. + +### Getting Started with Quarto on Spaces + +1. Create the Quarto space, and clone it locally + + + +2. **Install Quarto**: In order to render your Quarto site without Docker, we recommend installing Quarto by following the instructions on the [official Quarto website](https://quarto.org/docs/get-started/). + +3. **Install Quarto VS Code extension** the [Quarto VS Code Extention](https://quarto.org/docs/tools/vscode.html) includes a number of productivity tools including YAML Autocomplete, a preview button, and a visual editor. Quarto works great with VS Code, but the extension does make it easier to get the most out of Quarto. + +4. **Edit the site** The website files are contained in the `src` directory, and the site navigation is defined in `src/_quarto.yml`, try editing these files and either clicking the "Preview" button in VS Code, or calling `quarto preview src` from the command line. + +5. **Learn more about Quarto** You can do a lot of things with Quarto, and they are all documented on the [Quarto Website](https://quarto.org/guide/). In particular you may be interested in: + + - All about building [websites](https://quarto.org/docs/websites/) + - Building Static [Dashboards](https://quarto.org/docs/dashboards/) + - How to write [books](https://quarto.org/docs/books/index.html) and [manuscripts](https://quarto.org/docs/manuscripts/) + - Reproducible [presentations](https://quarto.org/docs/manuscripts/) + - Including [Observable](https://quarto.org/docs/interactive/ojs/) or [Shiny](https://quarto.org/docs/interactive/shiny/) applications in your Quarto site From f07cc462bf417230a0d91763bd1576d5eacabce1 Mon Sep 17 00:00:00 2001 From: Gordon Shotwell Date: Wed, 6 Mar 2024 09:49:04 -0400 Subject: [PATCH 2/6] Apply suggestions from code review Co-authored-by: Omar Sanseviero --- docs/hub/spaces-sdks-docker-quarto.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/hub/spaces-sdks-docker-quarto.md b/docs/hub/spaces-sdks-docker-quarto.md index afacc7d18..6c99a9a9f 100644 --- a/docs/hub/spaces-sdks-docker-quarto.md +++ b/docs/hub/spaces-sdks-docker-quarto.md @@ -1,7 +1,7 @@ # Quarto on Spaces -Quarto is a powerful tool for creating reproducible scientific and technical documents. -With Quarto you can interleave markdown and code chunks to generate pdfs, websites, presentations and more. +[Quarto](https://quarto.org/) is a powerful tool for creating reproducible scientific and technical documents. +With Quarto, you can interleave markdown and code chunks to generate pdfs, websites, presentations, and more. ### Getting Started with Quarto on Spaces @@ -11,11 +11,11 @@ With Quarto you can interleave markdown and code chunks to generate pdfs, websit 2. **Install Quarto**: In order to render your Quarto site without Docker, we recommend installing Quarto by following the instructions on the [official Quarto website](https://quarto.org/docs/get-started/). -3. **Install Quarto VS Code extension** the [Quarto VS Code Extention](https://quarto.org/docs/tools/vscode.html) includes a number of productivity tools including YAML Autocomplete, a preview button, and a visual editor. Quarto works great with VS Code, but the extension does make it easier to get the most out of Quarto. +3. **Install Quarto VS Code extension** the [Quarto VS Code Extention](https://quarto.org/docs/tools/vscode.html) includes a number of productivity tools, including YAML Autocomplete, a preview button, and a visual editor. Quarto works great with VS Code, but the extension does make it easier to get the most out of Quarto. -4. **Edit the site** The website files are contained in the `src` directory, and the site navigation is defined in `src/_quarto.yml`, try editing these files and either clicking the "Preview" button in VS Code, or calling `quarto preview src` from the command line. +4. **Edit the site** The website files are contained in the `src` directory, and the site navigation is defined in `src/_quarto.yml`, try editing these files and either clicking the "Preview" button in VS Code or calling `quarto preview src` from the command line. -5. **Learn more about Quarto** You can do a lot of things with Quarto, and they are all documented on the [Quarto Website](https://quarto.org/guide/). In particular you may be interested in: +5. **Learn more about Quarto** You can do a lot of things with Quarto, and they are all documented on the [Quarto Website](https://quarto.org/guide/). In particular, you may be interested in: - All about building [websites](https://quarto.org/docs/websites/) - Building Static [Dashboards](https://quarto.org/docs/dashboards/) From 03daac37aed4bdf565487ff2335f4bdb395a85f8 Mon Sep 17 00:00:00 2001 From: Gordon Shotwell Date: Wed, 6 Mar 2024 09:55:23 -0400 Subject: [PATCH 3/6] Reorganize TOC --- docs/hub/_toctree.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/hub/_toctree.yml b/docs/hub/_toctree.yml index a01d05c24..7087432a4 100644 --- a/docs/hub/_toctree.yml +++ b/docs/hub/_toctree.yml @@ -214,8 +214,6 @@ title: Livebook on Spaces - local: spaces-sdks-docker-shiny title: Shiny on Spaces - - local: spaces-sdks-docker-quarto - title: Quarto on Spaces - local: spaces-sdks-docker-zenml title: ZenML on Spaces - local: spaces-sdks-docker-panel @@ -226,6 +224,8 @@ title: Tabby on Spaces - local: spaces-sdks-docker-giskard title: Giskard on Spaces + - local: spaces-sdks-docker-quarto + title: Quarto on Spaces - local: spaces-embed title: Embed your Space - local: spaces-run-with-docker From a354a3d8d3245b40706352e5f6809887d55507a6 Mon Sep 17 00:00:00 2001 From: Gordon Shotwell Date: Wed, 6 Mar 2024 10:23:31 -0400 Subject: [PATCH 4/6] Break documentation into three sections --- docs/hub/spaces-sdks-docker-quarto.md | 60 ++++++++++++++++++++++----- 1 file changed, 49 insertions(+), 11 deletions(-) diff --git a/docs/hub/spaces-sdks-docker-quarto.md b/docs/hub/spaces-sdks-docker-quarto.md index 6c99a9a9f..795c1667f 100644 --- a/docs/hub/spaces-sdks-docker-quarto.md +++ b/docs/hub/spaces-sdks-docker-quarto.md @@ -3,22 +3,60 @@ [Quarto](https://quarto.org/) is a powerful tool for creating reproducible scientific and technical documents. With Quarto, you can interleave markdown and code chunks to generate pdfs, websites, presentations, and more. -### Getting Started with Quarto on Spaces +## Getting Started with Quarto on Spaces -1. Create the Quarto space, and clone it locally +### Edit the site on Hugging Face + +1. Create the Quarto space -2. **Install Quarto**: In order to render your Quarto site without Docker, we recommend installing Quarto by following the instructions on the [official Quarto website](https://quarto.org/docs/get-started/). +2. Edit in the browser + +You can make changes to the quarto site directly in Hugging Face. +There are three main types of files which you will need to edit in order to make changes: + +- The `src/_quarto.yml` file contains the site navigation, and is the best place to start if you want to change the structure of the site. +- The notebook and `.qmd` files in the `src` directory contain the actual content of the web pages. +- The `Dockerfile` contains the instructions for building the site. For example if you want to change the version of Quarto which the site uses, you should update the Dockerfile. + +3. Commit your changes and build the site + +### Local development + +Editing the site on Hugging Face is a convenient way to make small changes, but most of the time you will want to develop and preview the site locally before deploying. +This will allow you to view your changes more quickly, and to use the full power of the Quarto development environment. + +1. Create the Quarto space as above + +2. Clone the Repo + +To clone the space locally run the following command, make sure to replace `` with your Hugging Face username. + +``` +git clone https://huggingface.co/spaces//quarto-template +``` + +3. Install Quarto + +In order to render your Quarto site without Docker, we recommend installing Quarto by following the instructions on the [official Quarto website](https://quarto.org/docs/get-started/). + +3. Install Quarto VS Code extension + +The [Quarto VS Code Extention](https://quarto.org/docs/tools/vscode.html) includes a number of productivity tools, including YAML Autocomplete, a preview button, and a visual editor. Quarto works great with VS Code, but the extension does make it easier to get the most out of Quarto. + +4. Edit the site + The website files are contained in the `src` directory, and the site navigation is defined in `src/_quarto.yml`, try editing these files and either clicking the "Preview" button in VS Code or calling `quarto preview src` from the command line. -3. **Install Quarto VS Code extension** the [Quarto VS Code Extention](https://quarto.org/docs/tools/vscode.html) includes a number of productivity tools, including YAML Autocomplete, a preview button, and a visual editor. Quarto works great with VS Code, but the extension does make it easier to get the most out of Quarto. +5. Commit your changes and push + Your site will rebuild whenever you push new commits to main branch of the space repository -4. **Edit the site** The website files are contained in the `src` directory, and the site navigation is defined in `src/_quarto.yml`, try editing these files and either clicking the "Preview" button in VS Code or calling `quarto preview src` from the command line. +### Learn about Quarto -5. **Learn more about Quarto** You can do a lot of things with Quarto, and they are all documented on the [Quarto Website](https://quarto.org/guide/). In particular, you may be interested in: +You can do a lot of things with Quarto, and they are all documented on the [Quarto Website](https://quarto.org/guide/). In particular, you may be interested in: - - All about building [websites](https://quarto.org/docs/websites/) - - Building Static [Dashboards](https://quarto.org/docs/dashboards/) - - How to write [books](https://quarto.org/docs/books/index.html) and [manuscripts](https://quarto.org/docs/manuscripts/) - - Reproducible [presentations](https://quarto.org/docs/manuscripts/) - - Including [Observable](https://quarto.org/docs/interactive/ojs/) or [Shiny](https://quarto.org/docs/interactive/shiny/) applications in your Quarto site +- All about building [websites](https://quarto.org/docs/websites/) +- Building Static [Dashboards](https://quarto.org/docs/dashboards/) +- How to write [books](https://quarto.org/docs/books/index.html) and [manuscripts](https://quarto.org/docs/manuscripts/) +- Reproducible [presentations](https://quarto.org/docs/manuscripts/) +- Including [Observable](https://quarto.org/docs/interactive/ojs/) or [Shiny](https://quarto.org/docs/interactive/shiny/) applications in your Quarto site From 4c6060b1bf4607001d91e15c2ae43401ce0a149d Mon Sep 17 00:00:00 2001 From: Gordon Shotwell Date: Thu, 7 Mar 2024 09:44:29 -0400 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: Pedro Cuenca --- docs/hub/spaces-sdks-docker-quarto.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/hub/spaces-sdks-docker-quarto.md b/docs/hub/spaces-sdks-docker-quarto.md index 795c1667f..b7ce6f9de 100644 --- a/docs/hub/spaces-sdks-docker-quarto.md +++ b/docs/hub/spaces-sdks-docker-quarto.md @@ -18,7 +18,7 @@ There are three main types of files which you will need to edit in order to make - The `src/_quarto.yml` file contains the site navigation, and is the best place to start if you want to change the structure of the site. - The notebook and `.qmd` files in the `src` directory contain the actual content of the web pages. -- The `Dockerfile` contains the instructions for building the site. For example if you want to change the version of Quarto which the site uses, you should update the Dockerfile. +- The `Dockerfile` contains the instructions for building the site. For example, if you want to change the version of Quarto which the site uses, you should update the Dockerfile. 3. Commit your changes and build the site @@ -31,7 +31,7 @@ This will allow you to view your changes more quickly, and to use the full power 2. Clone the Repo -To clone the space locally run the following command, make sure to replace `` with your Hugging Face username. +To clone the space locally run the following command, making sure to replace `` with your Hugging Face username and `quarto-template` with the name you chose for your space. ``` git clone https://huggingface.co/spaces//quarto-template @@ -49,7 +49,7 @@ The [Quarto VS Code Extention](https://quarto.org/docs/tools/vscode.html) includ The website files are contained in the `src` directory, and the site navigation is defined in `src/_quarto.yml`, try editing these files and either clicking the "Preview" button in VS Code or calling `quarto preview src` from the command line. 5. Commit your changes and push - Your site will rebuild whenever you push new commits to main branch of the space repository + Your site will rebuild whenever you push new commits to the `main` branch of your space repository. ### Learn about Quarto From c5fa185456b97d4bc334cb06d2b700403b69e73a Mon Sep 17 00:00:00 2001 From: Gordon Shotwell Date: Thu, 7 Mar 2024 09:47:38 -0400 Subject: [PATCH 6/6] Further code review --- docs/hub/spaces-sdks-docker-quarto.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/hub/spaces-sdks-docker-quarto.md b/docs/hub/spaces-sdks-docker-quarto.md index b7ce6f9de..de9480b59 100644 --- a/docs/hub/spaces-sdks-docker-quarto.md +++ b/docs/hub/spaces-sdks-docker-quarto.md @@ -9,6 +9,8 @@ With Quarto, you can interleave markdown and code chunks to generate pdfs, websi 1. Create the Quarto space +Quarto spaces have very minimal compute requirements, so a small CPU space will be sufficient for most sites. You can create a space by clicking this button: + 2. Edit in the browser @@ -43,7 +45,7 @@ In order to render your Quarto site without Docker, we recommend installing Quar 3. Install Quarto VS Code extension -The [Quarto VS Code Extention](https://quarto.org/docs/tools/vscode.html) includes a number of productivity tools, including YAML Autocomplete, a preview button, and a visual editor. Quarto works great with VS Code, but the extension does make it easier to get the most out of Quarto. +The [Quarto VS Code Extention](https://quarto.org/docs/tools/vscode.html) includes a number of productivity tools, including YAML Autocomplete, a preview button, and a visual editor. Quarto works great without VS Code, but the extension does make it easier to get the most out of Quarto. 4. Edit the site The website files are contained in the `src` directory, and the site navigation is defined in `src/_quarto.yml`, try editing these files and either clicking the "Preview" button in VS Code or calling `quarto preview src` from the command line.