| --- | |
| title: "About Quarto" | |
| --- | |
| [Quarto](https://quarto.org/) is a Markdown-based documentation system that lets you write documents in Markdown or Jupyter Notebooks, and render them to a variety of formats including HTML, PDF, PowerPoint, and more. | |
| You can also use Quarto to write [books](https://quarto.org/docs/books/), create [dashboards](https://quarto.org/docs/dashboards/), and embed web applications with [Observable](https://quarto.org/docs/interactive/ojs/) and [Shinylive](https://quarto.org/docs/blog/posts/2022-10-25-shinylive-extension/). | |
| ## Getting started with Quarto | |
| Once you've created the space, click on the `Files` tab in the top right to take a look at the files which make up this Space. | |
| There are a couple of important files which you should pay attention to: | |
| - `Dockerfile`: This contains the system setup to build and serve the Quarto site on Hugging Face. You probably won't need to change this file that | |
| often unless you need to add additional system dependencies or modify the Quarto version. | |
| - `requirements.txt`: This is where you should include any Python dependencies which you need for your website. | |
| These are installed when the Dockerfile builds. | |
| - The `src` directory contains the source files for the Quarto website. You can include Jupyter notebooks or markdown (`.qmd` or `.md`) files. | |
| - `src/_quarto.yml` defines the navigation for your website. If you want to add new pages or reorganize the existing ones, you'll need to change this file. | |
| ## Recommended Workflow | |
| 1. **Clone the space 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 Extension](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/presentations/) | |
| - Including [Observable](https://quarto.org/docs/interactive/ojs/) or [Shiny](https://quarto.org/docs/interactive/shiny/) applications in your Quarto site | |
| ::: {.callout-warning} | |
| It can take a couple of minutes for the Space to deploy to Hugging Face after the Docker build process completes. Two see your changes you will need to do two things: | |
| 1) Wait for your space's status to go from 'Building' to 'Running'(this is visible in the status bar above the Space) | |
| 2) Force-reload the web page by holding Shift and hitting the reload button in your browser. | |
| ::: | |
| ## Code Execution | |
| One of the main virtues of Quarto is that it lets you combine code and text in a single document. | |
| By default, if you include a code chunk in your document, Quarto will execute that code and include the output in the rendered document. | |
| This is great for reproducibility and for creating documents that are always up-to-date. | |
| For example you can include code which generates a plot like this: | |
| ```{python} | |
| import seaborn as sns | |
| import matplotlib.pyplot as plt | |
| # Sample data | |
| tips = sns.load_dataset("tips") | |
| # Create a seaborn plot | |
| sns.set_style("whitegrid") | |
| g = sns.lmplot(x="total_bill", y="tip", data=tips, aspect=2) | |
| g = g.set_axis_labels("Total bill (USD)", "Tip").set(xlim=(0, 60), ylim=(0, 12)) | |
| plt.title("Tip by Total Bill") | |
| plt.show() | |
| ``` | |
| When the website is built the Python code will run and the output will be included in the document. | |
| You can also include [inline code](https://quarto.org/docs/computations/inline-code.html) to insert computed values into text. | |
| For example we can include the maximum tip value in the `tips` data frame like this: ``{python} tips['tip'].max()``. | |
| You can control [code execution](https://quarto.org/docs/computations/execution-options.html), or [freeze code output](https://quarto.org/docs/projects/code-execution.html#freeze) to capture the output of long running computations. | |
| ## About the Open Source AI Cookbook | |
| To provide a realistic example of how Quarto can help you organize long-form documentation, | |
| we've implemented the Hugging Face [Open-Source AI Cookbook](https://github.com/huggingface/cookbook) in Quarto. | |
| The Open-Source AI Cookbook is a collection of notebooks illustrating practical aspects of building AI applications and solving various machine learning tasks using open-source tools and models. | |
| You can read more about it, or contribute your own Notebook on the [Github Repo](https://github.com/huggingface/cookbook) | |