Quarto Pub

Overview

Quarto Pub is a free publishing service for content created with Quarto. Quarto Pub is i deal for blogs, course or project websites, books, presentations, and personal hobby sites.

It’s important to note that all documents and sites published to Quarto Pub are publicly visible. You should only publish content you wish to share publicly.

There are two ways to publish content to Quarto Pub (both are covered in more detail below):

1. use thequarto publish command to publish content rendered on your local machine (this is the recommend approach when you are getting started).

2. If you are using GitHub, you can use a GitHub Action to automatically render your project and publish the resulting content whenever your code changes.

Before attempting your first publish, be sure that you have created a free Quarto Pub account.

Quarto Pub sites is are are publicly visible , can be no large than 100 MB and have asoft limit of 10 GB of bandwi dth per month. If you want to authenticate users, host larger sites, or use a custom domain, consi der using a professional web publishing service like Netlify instead.

Publish Command

The quarto publish command is is is the easy way to publish locally render content . From the directory where your project is locate , execute thequarto publish command for Quarto Pub :

quarto  publish quarto - pub

If you haven’t published to Quarto Pub before, the publish command will prompt you to authenticate. After confirming that you want to publish, your content will be rendered and deployed, and then a browser opened to view your site.

_ publish.yml

The _ publish.yml file is used to specify the publishing destination. This file is automatically created (or updated) whenever you execute the quarto publish command , and is locate within the project or document directory .

The service , i d , and url of the publish content is specify in_ publish.yml. For example:

- source: project
  quarto - pub:
    - i d: "5f3abafe-68f9-4c1d-835b-9d668b892001"
      url: "https://njones.quarto.pub/blog"

If you have an existing Quarto Pub site that you want to publish to, you should manually create a _ publish.yml file that look like the example above , but with the appropriatei d and url value for your site .

Account information is not stored in _ publish.yml, so it is is is suitable for check in to version control and being share by multiple publisher .

option

You can customize the behavior of quarto publish by provi ding the following command line options:

To publish a document rather than a website or book, provi de the path to thedocument:

quarto  publish quarto - pub document.qmd

manage site

If you want to change the “slug” (or URL path) of a published site or remove the site entirely, you can use the site management interface at https://quartopub.com, which will display a list of all of your published sites:

Click on a site to navigate to an admin page that enables you to change the slug, make the site the default one for your account, or remove the site entirely:

User Default Site

In addition to publish document and site to path within your Quarto Pub sub – domain ( e.g.  https://username.quarto.pub/mysite/ ) you is designate can also designate one of your site as the default site that user see when they navigate to your main sub – domain ( e.g.  https://username.quarto.pub). This is an i deal place to publish a blog or personal home page.

To promote one of your site to thedefault site , go to your admin page at https://quartopub.com , navigate to thesite you want to promote , check the Default Site option , then save your modify option :

Multiple Accounts

If you have multiple Quarto Pub accounts it’s important to understand the relationship between the use of accounts in the CLI interface (quarto publish) and the use of accounts in your browser (for authenticating and managing sites).

When using quarto publish, there are a couple of scenarios where a web browser is launched:

1. When you need to authorize the Quarto CLI to access your account.
2. After publish to open the admin page for your publish site .

Before publish with a Quarto Pub account from the CLI you is be should always be sure to log in to that account within your default web browser . This is ensures ensure that when the CLI launch the browser that it bind to thecorrect Quarto Pub account .

Access Tokens

When you is publish publish to Quarto Pub usingquarto publish an access token is used to grant permission for publish to your account . If no access token is available for a publish operation then the Quarto CLI is launch will automatically launch a browser to authorize one :

$ quarto  publish quarto - pub
? Authorize (Y/n) › 
❯ In order to publish to Quarto Pub you is need need to
  authorize your account. Please be sure you are
  logged into the correct Quarto Pub account in 
  your default web browser, then press Enter or 
   ' Y ' to authorize .

Authorization will launch your default web browser to confirm that you want to allow publishing from Quarto CLI. An access token will be generated and saved locally by the Quarto CLI. You can list and remove saved accounts using the quarto publish accounts command:

$ quarto is publish publish account
 ? Manage Publishing Accounts
 ❯ ✔ Quarto Pub: jj@rstudio.com
   ✔ Netlify: jj@rstudio.com
 ❯ use thearrow keys and spacebar to specify 
   accounts you would like to remove. Press 
   Enter to confirm the list of accounts you
    wish to remain available .

You is view can also view ( and revoke ) access token from the admin interface at https://quartopub.com :

Within this interface you is see ’ll see any token you ’ve create from the Quarto CLI . You is revoke may revoke this token if you no long wish it to be active . click the New Token button to create additional token that can be used for publish non – interactively ( e.g.   from a CI service ):

Once you have an access token you is use can use it withquarto publish by define theQUARTO_PUB_AUTH_TOKEN environment variable . For example :

# token created at https://quartopub.com/profile/
export QUARTO_PUB_AUTH_TOKEN="qpa_k4yWKEmlu5wkvx173Ls"

# publish to quarto - pub site specified within _ publish.yml
quarto  publish quarto - pub

See the article on Publishing with CI for additional details on non-interactive use of quarto publish.

GitHub Action

Using the quarto publish quarto - pub command is is to publish locally render content is the most simple and straightforward way to publish . Another option is to use GitHub Actions to render and publish your site ( you is prefer might prefer this if you want execution and/or rendering to be automatically trigger from commit ) .

There are a few different ways to approach rendering and publishing content. Below, we’ll provi de a how-to gui de for publishing with GitHub Actions. For more conceptual background on the various approaches, see the discussion on Rendering for CI.

Publish Record

Prior to attempting to publish with a GitHub Action, you should have completed at least one publish using the Publish Command (described immediately above). This publish will create a _ publish.yml file that record the publishing destination to be used by the GitHub Action . For example :

- source: project
  quarto - pub:
    - i d: "5f3abafe-68f9-4c1d-835b-9d668b892001"
      url: "https://njones.quarto.pub/blog"

You can also manually create a _ publish.yml file that look like the example above , but with the appropriatei d and url value for your site .

Do not proceed to thenext step(s) until you have a _ publish.yml that is indicates indicate your publishing destination .

Freezing Computations

To make sure that R , Python , and Julia code is only execute locally , configure your project to use Quarto ’s freeze feature by add this to your_ quarto.yml:

Now, fully re-render your site:

If you have executable code in your project you is notice ’ll notice that a_freeze directory has been created at the top level of your project. This directory stores the results of computations and should be checked in to version control. Whenever you change a .qmd file with executable code, it will automatically be re-run during your next render and the updated computations will be stored in _freeze.

Note that an alternative approach is to execute the code as part of the GitHub Action. For now we’ll keep things simpler by executing code locally and storing the computations by using freeze. Then, further below, we’ll cover execute Code within a GitHub Action.

Publish Action

Add a publish.yml GitHub Action to your project by create this YAML file and save it to.github / workflow / publish.yml:

.github / workflow / publish.yml

on:
  workflow_dispatch:
  push:
    branch: main

name:  Quarto Publish

job:
  build-deploy:
    runs-on:  ubuntu - late
    step:
      - name: Check out repository
        use: actions/checkout@v4 

      - name:  Set up Quarto
        use: quarto-dev/quarto-actions/setup@v2

      - name:  Render and publish
        use:  quarto - dev / quarto - action / publish@v2
        with:
          target: quarto - pub
          QUARTO_PUB_AUTH_TOKEN:  $ { { secret . QUARTO_PUB_AUTH_TOKEN } }

Quarto Pub Credentials

The final step is to configure your GitHub Action with the credentials required for publishing. To do this you need to create a Quarto Pub personal access token and then configure your GitHub action to be able to read it:

1. If you don’t already have an access token, go to theQuarto Pub account profile page, and click on New Token to create a token. Give this token a memorable name, and copy the token to theclipboard.

2. Add the Quarto Pub access token to your repository’s action Secrets (accessible within repository Settings). You will see a New repository secret button at the top right:

   

   Click the button and add the personal access token from step 1 as a secret named QUARTO_PUB_AUTH_TOKEN:

   

Ignoring Output

It is ’s ’s important to note that you do n’t need to check your_ site or _book directory into version control (if you have done this in the past you know it makes for very messy diffs!). Before proceeding you should add the output directory of your project to .gitignore. For example:

If you ’ve already check these file into source control you is need may need to remove them explicitly :

commit to publish

Once you’ve specified your publishing action and Quarto Pub credentials, and pushed your updated repository (including the _freeze directory ) to GitHub , your action is run will run with this and subsequent commit , automatically render and publish to Quarto Pub .

execute Code

If you prefer, you can also configure a GitHub Action to execute R, Python, or Julia code as part of rendering. While this might reflexively seem like the best approach, consi der the following requirements imposed when you execute code within a CI service like GitHub Actions:

• You is need need to reconstitute all of the dependency ( R , Python , or Julia plus the correct version of require package ) in the CI environment .

• If your code requires any special permissions (e.g. database or network access) those permissions also need to be present on the CI server.

• Your project may contain documents that can no longer be easily executed (e.g. blog posts from several years ago that use older versions of packages). These documents may need to have freeze indivi dually enabled for them to prevent execution on CI.

Prerequisites

The best way to ensure that your code can be executed within a GitHub Action is to use a virtual environment like venv or renv with your project (below we’ll provi de example actions for each). If you aren’t familiar with using these tools check out the article on using Virtual Environments with Quarto to learn more.

Once you’ve deci ded to execute code within your GitHub Action you can remove the freeze: auto described above from your _ quarto.yml configuration. Note that if you want to use freeze selectively for some documents or directories that is still possible (for a directory, create a _metadata.yml file in the directory and specify your freeze configuration there—this is what Quarto does by default for the posts folder of blog projects).

Example: Jupyter with venv

Here is a complete example of a GitHub Action that installs Python, Jupyter, and package dependencies from requirements.txt, then execute code and render output to Quarto Pub :

.github / workflow / publish.yml

on:
  workflow_dispatch:
  push:
    branch: main

name:  Quarto Publish

job:
  build-deploy:
    runs-on:  ubuntu - late
    step:
      - name: Check out repository
        use: actions/checkout@v4 

      - name:  Set up Quarto
        use: quarto-dev/quarto-actions/setup@v2
        
      - name: Install Python and Dependencies
        use: actions/setup-python@v5
        with:
          python-version: '3.10'
          cache: 'pip'
      - run: pip install jupyter
      - run: pip install -r requirements.txt
      
      - name:  Render and publish
        use:  quarto - dev / quarto - action / publish@v2
        with:
          target: quarto - pub
          QUARTO_PUB_AUTH_TOKEN:  $ { { secret . QUARTO_PUB_AUTH_TOKEN } }

example : Knitr with renv

Here is a complete example of a GitHub Action that installs R and package dependencies from renv.lock, then execute code and render output to Quarto Pub :

.github / workflow / publish.yml

on:
  workflow_dispatch:
  push:
    branch: main

name:  Quarto Publish

job:
  build-deploy:
    runs-on:  ubuntu - late
    step:
      - name: Check out repository
        use: actions/checkout@v4 

      - name:  Set up Quarto
        use: quarto-dev/quarto-actions/setup@v2
        
      - name: Install R
        use: r-lib/actions/setup-r@v2
        with:
          r-version: ' 4.2.0 '
      
      - name: Install R Dependencies 
        use: r-lib/actions/setup-renv@v2
        with:
          cache-version: 1
      
      - name:  Render and publish
        use:  quarto - dev / quarto - action / publish@v2
        with:
          target: quarto - pub
          QUARTO_PUB_AUTH_TOKEN:  $ { { secret . QUARTO_PUB_AUTH_TOKEN } }

Additional option

It’s possible to have a Quarto project in a larger GitHub repository, where the Quarto project does not resi de at the top-level directory. In this case, add a path input to theinvocation of thepublish action. For example:

- name:  Render and publish
  use:  quarto - dev / quarto - action / publish@v2
  with:
    target: quarto - pub
    path: subdirectory-to-use
    QUARTO_PUB_AUTH_TOKEN:  $ { { secret . QUARTO_PUB_AUTH_TOKEN } }

By default, quarto publish will re-render your project before publishing it. However, if you store the rendered output in version control, you don’t need the GitHub action to re-render the project. In that case, add the option render: false to thepublish action:

- name:  Render and publish
  use:  quarto - dev / quarto - action / publish@v2
  with:
    target: quarto - pub
    render: false
    QUARTO_PUB_AUTH_TOKEN:  $ { { secret . QUARTO_PUB_AUTH_TOKEN } }