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,79 @@
+---
+title: "Hugging Face Spaces"
+provider: huggingface
+provider-name: Hugging Face
+---
+
+{{< include ../prerelease/1.5/_pre-release-feature.qmd >}}
+
+## Overview
+
+[Hugging Face Spaces](https://pages.github.com/) allow users to easily deploy ML-powered models and demos, and Quarto is a great way for you 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, which Hugging Face has made easily available for authors.
+
+To create and publish a Hugging Face Space using Quarto, use the following steps, explained at length below:
+
+1. [Create a new space using Quarto's Docker Template](#create-a-new-space)
+
+1. (Optional) [Create an authorization token if you need or lack one](#create-an-authorization-token)
+
+1. [Clone the repository locally](#clone-the-repository-locally)
+
+1. Use Quarto project
+
+1. [Run `quarto publish huggingface`](#run-quarto-publish-huggingface)
+
+
+## Instructions
+
+### Create a new space
+
+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, you will see the following dialog. Log in first.
+
+![The UI for logging in to Hugging Face](./images/hugging-face-login-ui.png)
+
+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)
+
+If you followed the link above, you will then see the "Docker" option selected, as well as the Quarto template. 
+If not, select them as shown below.
+
+![The UI for Hugging Face Spaces creation webpage](./images/hugging-face-create-ui.png)
+
+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)
+
+### 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.
+
+### 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-you-just-chose>`.
+
+Use your favorite `git` interface to clone the Hugging Face Space you've just created with the URL above.
+
+### Make local edits to your Quarto project
+
+Use Quarto from 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](https://quarto.org/docs/websites/)
+
+### Run `quarto publish huggingface`
+
+When you are happy with the results in the repository, type `quarto publish huggingface` from your preferred shell.
+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 an authorization token, Quarto will prompt you for such information on the command line.
+
+## Additional information
+
+**You can work from an existing repository**: `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. 
+But if you have a `git` 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.
+