document quarto publish huggingface

_quarto.yml

@@ -386,6 +386,7 @@ website:
               - docs/publishing/posit-cloud.qmd
               - docs/publishing/netlify.qmd
               - docs/publishing/confluence.qmd
+              - docs/publishing/hugging-face.qmd
               - docs/publishing/other.qmd
               - text: "Publishing with CI"
                 href: docs/publishing/ci.qmd

docs/publishing/_providers.md

@@ -8,6 +8,7 @@
 | [Posit Cloud](/docs/publishing/posit-cloud.qmd)       | Create data projects and publish results from your web browser. Use Posit Cloud when you want to organize all your static documents and interactive applications in one place.                  |
 | [Netlify](/docs/publishing/netlify.qmd)                 | Professional web publishing platform. Use Netlify when you want support for custom domains, authentication, previewing branches, and other more advanced capabilities.                          | 
 | [Confluence](/docs/publishing/confluence.qmd)         | Publishing platform for supporting team collaboration. Use Confluence to share documents in team Spaces.                                                            |
+| [Hugging Face Spaces](/docs/publishing/hugging-face.qmd)       | Publishing platform specializing in learning models and datasets. Use Hugging Face Spaces when you want to share Quarto documents together with associated machine learning models and/or datasets.                      |
 | [Other Services](/docs/publishing/other.qmd)            | Content rendered with Quarto uses standard formats (HTML, PDFs, MS Word, etc.) that can be published anywhere. Use this if none of the methods above meets your requirements.               |
 
 : {tbl-colwidths="\[30,70\]"}

docs/publishing/hugging-face.qmd

@@ -0,0 +1,124 @@
+---
+title: "Hugging Face Spaces"
+provider: huggingface
+provider-name: Hugging Face
+---
+
+## Overview
+
+Hugging Face is a comprehensive platform that offers a wide array of machine learning models, particularly in natural language processing (NLP) and computer vision. It is designed to facilitate the training, deployment, and use of open-access machine learning models, making it easier for developers and researchers to access state-of-the-art models. 
+
+Hugging Face also provides application and static site hosting as part of its [Spaces project](https://huggingface.co/docs/hub/spaces-overview). You can use [Hugging Face Spaces](https://pages.github.com/) to render and host Quarto websites as a way to document and present your work.
+
+Quarto's integration in Hugging Face Spaces happens through a [Docker](https://www.docker.com/) image created by the Quarto team that Hugging Face has made easily available for authors as a template. 
+
+To create and publish a Hugging Face Space using Quarto, you'll start by creating a new space using Quarto's Docker Template. Then you'll edit or replace the example content with your own. Learn more about this process in [Getting Started](#getting-started) below.
+
+Whenever changes are committed to your Hugging Face Space, a new build is initiated which renders and serves your Quarto website. You can make and commit changes directly in the Hugging Face UI. However, previewing your changes via a build on Hugging Face is time-consuming, so for faster iteration we recommend working locally and using the `quarto publish huggingface` command.  This workflow is described below in [Publish Command](#publish-command).
+
+## Getting Started 
+
+### Create a New Space
+
+To get started you'll create a new Hugging Face Space using the Quarto template. 
+
+Visit [the Hugging Face Create a New Space webpage](https://huggingface.co/new-space?template=posit%2Fquarto-template). 
+
+If you're not logged in to Hugging Face, log in first:
+
+![The UI for logging in to Hugging Face](./images/hugging-face-login-ui.png){width=50% fig-align="left" fig-alt="Screenshot of UI for logging in to Hugging Face."}
+
+Start by choosing a name and license for your space:
+
+![The UI for choosing name and license for your space](./images/hugging-face-choose-name-ui.png){.border fig-alt="Screenshot of Hugging Face UI for space creation consisting of three text boxes labelled: Owner, Space name and License."}
+
+If you followed the link above, you will see "Docker" selected for the Space SDK, and "Quarto" chosen as the Docker template. 
+If not, select them as shown below:
+
+![The UI for Hugging Face Spaces creation webpage](./images/hugging-face-create-ui.png){.border fig-alt="Screenshot of Hugging Face UI for selecting the space SDK and template. The Docker SDK and Quarto template are highlighted."}
+
+Finally, choose the hardware that will be used to run your space, whether the space will be public or private, and click on "Create Space":
+
+![The UI for choosing hardware configuration and space visibility](./images/hugging-face-hardware-ui.png){.border fig-alt="Screenshot of Hugging Face UI showing: a dropdown labelled 'Space Hardware', two radio buttons labelled Public (selected) and Private, and a button labelled 'Create Space'."}
+
+Hugging Face will then "Build" your space:
+
+![Build process for a new space based on the Quarto template](images/hugging-face-build.png){.border fig-alt="Screenshot of the Build log in a Hugging Face Space. Log starts with and ends with"}
+
+Once built, your Space will display the rendered example website (you may need to refresh the page in your browser for this to appear):
+
+![A Quarto template website running in a Hugging Face Space](images/hugging-face-complete.png){.border fig-alt="Screenshot of a Hugging Face Space, displaying a website with the title ''."}
+
+### Quarto's Hugging Face Template
+
+You can click on the `Files` tab in the top right to look at the files which make up the template. Quarto's Hugging Face template consists of files used to create an environment to build and render the Quarto website (`Dockerfile`and `requirements.txt`), and the website source itself in `src/`:
+
+- `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 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.
+
+You can edit these files directly in the Hugging Face UI but we reccommend cloning your space, and making and previewing changes locally, then using the publish command as described in the next section.
+
+## Publish Command
+
+{{< include ../prerelease/1.5/_pre-release-feature.qmd >}}
+
+The `quarto publish huggingface` command facilitates a workflow where you [make and preview edits](#edit-and-preview) locally before [publishing](#publish) to your Hugging Face space. Before using the command you'll need to complete some [Setup](#setup).
+
+### Setup
+
+To get set up to use `quarto publish huggingface` you should have already:
+
+(@) [Created a space using Quarto's Docker Template](#create-a-new-space) as described above. 
+
+Then complete the following steps, explained at length below:
+
+(@) (Optional) [Create an authorization token if you lack one](#create-an-authorization-token)
+
+(@) [Clone the repository locally](#clone-the-repository-locally)
+
+#### Create an authorization token
+
+In order to publish the results to Hugging Face, `quarto publish` needs access to your credentials. 
+If you haven't created such an authorization token yet, visit [Hugging Face's documentation on user access tokens](https://huggingface.co/docs/hub/security-tokens#how-to-manage-user-access-tokens) and follow the instructions to create a token with the `write` role. You'll need this token the first time you run the publish command.
+
+#### Clone the repository locally
+
+The URL for your space, as well as the URL to clone the repository, is `https://huggingface.co/spaces/<your-hugging-face-username>/<name-of-space>`. Use your favorite `git` interface to clone the Hugging Face Space you've just created with the URL above. You can also find instructions in your space under **⋮** > **Clone repository**.  
+
+### Edit and Preview 
+
+Once your repository is set up, use whichever text editor you prefer to make changes to your repository. 
+Quarto's Hugging Face template includes a Quarto website in the `src/` directory of the repository. For information on how to create websites with Quarto, see [our documentation](/docs/websites/website-basics.qmd)
+
+To preview your changes, from the root of your repository, run:
+
+```{.bash filename="Terminal"}
+quarto preview src
+```
+
+### Publish 
+
+When you are happy with the results in the repository, run: 
+
+```{.bash filename="Terminal"}
+quarto publish huggingface
+```
+
+Quarto will stage, commit, and push all required changes to Hugging Face, as well as fetching remote content and merging it with your repository's contents first.
+If the repository you're working on hasn't been configured to take in an explicit user name and authorization token, Quarto will prompt you for such information on the command line.
+
+On completion Quarto will open your space in your default browser. 
+
+## Publishing an Existing Repository
+
+The command `quarto publish huggingface` requires that the `origin` [git remote](https://docs.github.com/en/get-started/getting-started-with-git/managing-remote-repositories) point to a `https://huggingface.co/spaces` URL.
+If you used the instructions above, this will happen automatically. 
+
+If you are working from an existing repository already configured with a Quarto template pointing to the right URL, you can use `quarto publish huggingface` directly without needing to create or clone a new space.
+