Quarto Publish
Overview
The quarto publish command enables you to easily publish websites and documents to a variety of services, including Netlify, GitHub Pages and Posit Connect (more services will be added over time).
To publish a website or book, just execute quarto publish from within the project directory:
As with quarto render, you can also publish a project or document by name:
If you haven't previously published the target, you'll be prompted for a publishing destination (including which service you want to publish to, account credentials, etc.). If you have published before you'll get a confirmation prompt for re-publishing (along with the choice to publish to publish to another destination).
Publish Records
A record of your previous publishes will be stored in a _publish.yml file within the project or document directory. This file stores the service, id, and URL of the published content. For example:
Account information is not stored in this file, so it is suitable for checking in to version control and being shared by multiple publishers.
Note that GitHub Pages publishes are not stored in the _publish.yml file (they are tracked by virtue of the creation of a gh-pages branch).
If you provide the --id option (described below) then a publish record is not saved (as in that case you already have another means for tracking published content).
Headless / CI Usage
As an alternative to providing account credentials interactively, you case use the following environment variables:
| Service | Variables |
|---|---|
| Netlify | NETLIFY_AUTH_TOKEN |
| Postit Connect | CONNECT_SERVER and CONNECT_API_KEY |
Using an environment variable combined with a _publish.yml file that points to the requisite publishing destination is enough to enable the following command to perform a headless publish on CI:
GitHub Pages publishing requires no special environment variables (as it use the version of git available on your system or on the CI server).
Command Line
As an alternative to using a _publish.yml file, you can also specify your publish destination explicilty on the command line using a provider name (e.g. netlify or connect) along with the --id option. For example:
If your credentials are not stored in an environment variable as described above, you can optionally provide them the command line. For example:
When publishing to Posit Connect you should make sure that the server, token, and id are all available either via environment variables or the command line. For example:
Publish Options
By default quarto publish will prompt you to confirm actions, automatically re-render prior to publishing, and open a browser to the admin page for the published content after it completes. You can override this behavior using the following options:
| Option | Behavior |
|---|---|
| --no-prompt | Do not prompt to confirm publish actions. |
| --no-browser | Do not open a browser after publish. |
| --no-render | Do not re-render prior to publish |
Note that when running in a non-interactive context (e.g. on a CI server) quarto publish will automatically disable prompting and opening a browser.
Account Management
When you provide credentials for a publishing service they are remembered for future interactions with that same service (credentials are stored in the user app data directory with restrictive file permissions). If you want to review and/or remove registered accounts, execute the quarto publish accounts command:
You'll be presented with a list of accounts and you can interactively select one more accounts to remove.