Quarto Custom domain on GitHub Pages

This blog is published using the excellent Quarto framework to GitHub Pages which offers free website hosting. However, astute readers familiar with this sort of setup will have noticed that the domain is no the usual [github-user].github.io and instead it resolves to blog.nshephard.dev. This post explains how to achieve that as it took me a little bit of work to sort out properly.

The Bernia Ridge by Me

Why?

I found that despite setting a custom domain in the GitHub pages Settings (Settings > Pages > Custom domain) each time I published the site (e.g. on a new blog post) the CNAME file disappeared from the gh-pages branch and the domain didn’t resolve. I searched but couldn’t find a solution to this so raised an issue to include it in the quarto-actions.

In the meantime I added a custom step to the publish.yaml to add the CNAME file to the gh-pages branch after Render and Publish which worked, but I was subsequently pointed to a cleaner existing way of achieving the same result.

What isn’t covered

This post doesn’t cover…

• How to setup a blog/website using Quarto.
• How to write Quarto Markdown.
• How to publish a blog or website using Quarto, they have excellent documentation
• Setting a CNAME with your DNS registrar.

On this last point, how you set your CNAME to redirect your custom domain to that of the GitHub Pages is dependent on the domain registrar service you use. I use OVH.

What is covered

• How to add a CNAME file to the gh-pages branch that is produced by the quarto-dev/quarto-actions/publish GitHub Action so that the pages resolve to a custom domain.

The Problem

If you use plain GitHub Pages then you can set a custom CNAME by going to Settings > Pages > Custom Domain and entering the address there. However, as documented (see item 4) this doesn’t work if you use a custom GitHub Action to publish your website, which is the case when you use the quarto-dev/quarto-actions/publish GitHub Action to publish using Quarto.

Why? Because each time the action runs it regenerates the content of the gh-pages branch on the runner and pushes it to your repository and doesn’t include a custom CNAME file.

Solution 1

The solution I initially hit upon was to add an extra step to my .github/workflows/publish.yaml that…

1. Checks out the gh-pages branch.
2. Creates the CNAME file with the domain I use.
3. Adds this to the gh-pages branch.
4. Pushes back up-stream.

You should already have added a publish action to your repository which runs the quarto-dev/quarto-actions/publish GitHub Action. This runs quarto publish $TARGET where $TARGET is set by the chosen output configured in the target argument. In this example gh-pages

      - name: Render and Publish
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

After this you should add the following, substituting blog.nshephard.dev for your own domain.

      - name: Add CNAME file to gh-pages branch
        run: |
          rm renv/activate.R
          git switch gh-pages
          git pull
          echo 'blog.nshephard.dev > CNAME
          git add CNAME
          git commit -m "Adding CNAME"
          git push

This…

1. Removes the lingering renv/activate.R which prevents switching branches.
2. Switches branches to gh-pages.
3. git pull to get the just published version of the branch.
4. Creates the CNAME file with the domain you specify.
5. Adds (stages) the CNAME file to the gh-pages branch.
6. Commits the change.
7. Pushes the commit to origin (i.e. the gh-pages branch on GitHub)

This worked as the CNAME file is added each time the workflow runs but, unsurprisingly, there is a simpler solution.

Solution 2 - The correct way of doing this

Turns out the answer provided by @cscheid is, unsurprisingly, much simpler.

You need to add CNAME in the _quarto.yaml so that it is included in the project.

project:
  type: website
  resources:
    ...
    - "CNAME"

You also have to create and add the CNAME file with your domain to the repository.

echo 'blog.nshephard.dev` > CNAME
git add CNAME
git commit -m "Adding CNAME to repository"
git push

Then, because its included in the resources, the file will carry through/persist when the publishing action runs to create the gh-pages branch.

Related

This feature was introduced in Quarto 1.2 and others have encountered problems with the file being deleted on first running quarto publish gh-pages (if you’re having problems perhaps worth keeping an eye on that thread).

There is a draft Pull Request to add it to the documentation its not been merged which is perhaps why I couldn’t find how to do this in the documentation (see also discussion in this issue).