github pages setup for this website

github pages

Setting up a Quarto website is not trivial. Here is my setup to publish a single github repository using the DNS.


March 27, 2024

1 Desired setup

Setting up a Quarto website on github pages is fairly straightforward: you just need to follow the docs! But in case you need some help, I’m sharing here all the steps I’ve went through.

In my case, I thought there would be a slight complication. I want to have multiple pages from multiple repositories:

  • one for my personal website (on which you are right now).
  • one for my other Quarto projects. For each one, I want to have an associated github pages which can serve as a demo or readme.

My initial plan was the following:

I want the personnal website to use the root domain and the default subodmain while I want project pages to use another subdomain I would like project_a to live under:, etc.

This didn’t work out at all, so I’ve brought all repositories together for now, a summarized in Figure 1.

flowchart LR
    subgraph github
        direction TB
    subgraph urls
        direction TB
    A[Website repository] --> B[]
    B -- use URL --- BB[]
    C[Project A] --> D[] -- use URL --- DD[]
    E[Project B] --> F[] -- use URL --- FF[]
Figure 1

In the future, it would be straightforward to pull out any demo into its own subdomain, but I’ll first test out the current setup and see if I can make it work. I’m a bit unhappy about the current demo having a different style than the rest of the website but I can live with it.

2 Steps

2.1 Standard deploy to github pages

Quarto configuration

First, we need a Quarto website. I have decided that I will render the website on my machine, and that github will just serves the files once they are uploaded (corresponding to this section of the docs).

Thus, we just change the global website configuration so that quarto render compiles to the docs folder:

    type: website
    output-dir: docs

github configuration

Now, we need to setup github:

  • add a .nojekyll file at the root of repository.
  • create a new github repository with the specific repository name
    • normally, github associates to a given repository.
    • if we use this special repository name, github uses the root URL
  • push the project to the remote repository.
  • go to settings >> pages and tell github pages to publish from the docs folder on the main branch.

At this point, the page website is fully functional. Now we need to host it on its the custom domain.

2.2 Custom domain for github page

Quarto configuration

We will make it so that the website answers to my custom url If we omit this step, the website will act as if the custom url just acts as a redirect to the pages url.

First, we need to tell Quarto about the custom url:

  • create a cname file at the project root containing the custom url:

  • modify the project configuration file: _quarto.yml to include the cname file and so that Quarto uses the custom url:

        # publishing to github pages
        # ref:
        type: website
        output-dir: docs
            - CNAME
        title: "Guillaume Dehaene"
  • render and push to github.

Gandi DNS configuration

We will configure the DNS server so that it knows to serve the custom url to the right github pages url.

On gandi, I get to set the DNS configuration manually.

@ 10800 IN SOA 1711531617 10800 3600 604800 10800
@ 1800 IN A
@ 1800 IN A
@ 1800 IN A
@ 1800 IN A
www 10800 IN CNAME
demo 10800 IN CNAME

NB: the IP addresses are documented on this page of the github docs.

I’m honestly a bit confused about exactly what is going on under the hood here, but as far as I can tell:

  • the first four lines set the binding between the root domain and my github page.
  • the fifth line sets the binding specifically for the www subdomain.
  • the sixth line sets the binding specifically for the demo subdomain. Initially, I wanted to use this to host the demo pages for my Quarto projects, but I’m not using it currently.

There’s an underlying magic step where github knows, because of the cname file that we need to add in each repository, which pages correspond to which subdomain:

  • the website cname file contains on websites that should use that domain. Currently, that is all my repositories.
  • the website cname file contains on websites that should use that domain. I have tested that this works on a single demo repo. I’m not sure what would happen if I hooked up two. Github might be very confused if I do that 🤷.

github configuration

Finally, we tell github about the cname:

  • go to settings >> pages and tell github pages to use a Custom domain and specify your desired full domain.
  • wait a day, then enable https.

As a security precaution, please also verify your domain with github pages.

Back to top