github pages setup for this website

quarto

github pages

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

Published

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 guillaumedehaene.com and the default subodmain www.guillaumedehaene.com while I want project pages to use another subdomain demo.guillaumedehaene.com. I would like project_a to live under: demo.guillaumedehaene.com/project_a, 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
        A
        C
        E
    end
    subgraph urls
        direction TB
        B
        BB
        D
        DD
        F
        FF
    end
    A[Website repository] --> B[guillaumedehaene.github.io]
    B -- use URL --- BB[www.guillaumedehaene.com]
    C[Project A] --> D[guillaumedehaene.github.io/project_a] -- use URL --- DD[www.guillaumedehaene.com/project_a]
    E[Project B] --> F[guillaumedehaene.github.io/project_b] -- use URL --- FF[www.guillaumedehaene.com/project_b]

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

2.1.1 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:

_quarto.yml

project:
    type: website
    output-dir: docs

2.1.2 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 USERNAME.github.io.
- normally, github associates USERNAME.github.io/REPOSITORY_NAME to a given repository.
- if we use this special repository name, github uses the root URL USERNAME.github.io.
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 guillaumedehaene.github.io is fully functional. Now we need to host it on its the custom domain.

2.2 Custom domain for github page

2.2.1 Quarto configuration

We will make it so that the website answers to my custom url www.guillaumedehaene.com. 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:
```
cname
```
```
www.guillaumedehaene.com
```

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

_quarto.yml

project:
    # publishing to github pages
    # ref: https://quarto.org/docs/publishing/github-pages.html#render-to-docs
    type: website
    output-dir: docs
    resources:
        - CNAME

website:
    title: "Guillaume Dehaene"
    site-url: www.guillaumedehaene.com

render and push to github.

2.2.2 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 ns1.gandi.net. hostmaster.gandi.net. 1711531617 10800 3600 604800 10800
@ 1800 IN A 185.199.108.153
@ 1800 IN A 185.199.109.153
@ 1800 IN A 185.199.110.153
@ 1800 IN A 185.199.111.153
www 10800 IN CNAME guillaumedehaene.github.io.
demo 10800 IN CNAME guillaumedehaene.github.io.

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 guillaumedehaene.com 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 www.guillaumedehaene.com on websites that should use that domain. Currently, that is all my repositories.
the website cname file contains demo.guillaumedehaene.com 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 🤷.

2.2.3 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.

--- title: "github pages setup for this website" description: | Setting up a Quarto website is not trivial. Here is my setup to publish a single github repository using the www.gandi.net DNS. date: "03/27/2024" categories: - quarto - github pages --- # Desired setup Setting up a Quarto website on github pages is fairly straightforward: [you just need to follow the docs](https://quarto.org/docs/publishing/github-pages.html)! 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 `guillaumedehaene.com` and the default subodmain `www.guillaumedehaene.com` while I want project pages to use another subdomain `demo.guillaumedehaene.com`. I would like `project_a` to live under: `demo.guillaumedehaene.com/project_a`, etc. This didn't work out at all, so I've brought all repositories together for now, a summarized in @fig-structure. ```{mermaid} %% | label: fig-structure flowchart LR subgraph github direction TB A C E end subgraph urls direction TB B BB D DD F FF end A[Website repository] --> B[guillaumedehaene.github.io] B -- use URL --- BB[www.guillaumedehaene.com] C[Project A] --> D[guillaumedehaene.github.io/project_a] -- use URL --- DD[www.guillaumedehaene.com/project_a] E[Project B] --> F[guillaumedehaene.github.io/project_b] -- use URL --- FF[www.guillaumedehaene.com/project_b] ``` 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. # Steps ## 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](https://quarto.org/docs/publishing/github-pages.html#render-to-docs)). Thus, we just change the global website configuration so that `quarto render` compiles to the `docs` folder: ```{.yaml filename="_quarto.yml"} project: 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** `USERNAME.github.io`. - normally, github associates `USERNAME.github.io/REPOSITORY_NAME` to a given repository. - if we use this special repository name, github uses the root URL `USERNAME.github.io`. - 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 `guillaumedehaene.github.io` is fully functional. Now we need to host it on its the custom domain. ## Custom domain for github page ### Quarto configuration We will make it so that the website answers to my custom url `www.guillaumedehaene.com`. 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: ```{filename="cname"} www.guillaumedehaene.com ``` - modify the project configuration file: `_quarto.yml` to include the cname file and so that Quarto uses the custom url: ```{.yaml filename="_quarto.yml"} project: # publishing to github pages # ref: https://quarto.org/docs/publishing/github-pages.html#render-to-docs type: website output-dir: docs resources: - CNAME website: title: "Guillaume Dehaene" site-url: www.guillaumedehaene.com ``` - 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 ns1.gandi.net. hostmaster.gandi.net. 1711531617 10800 3600 604800 10800 @ 1800 IN A 185.199.108.153 @ 1800 IN A 185.199.109.153 @ 1800 IN A 185.199.110.153 @ 1800 IN A 185.199.111.153 www 10800 IN CNAME guillaumedehaene.github.io. demo 10800 IN CNAME guillaumedehaene.github.io. ``` NB: [the IP addresses are documented on this page of the github docs](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-an-apex-domain). 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 `guillaumedehaene.com` 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 `www.guillaumedehaene.com` on websites that should use that domain. Currently, that is all my repositories. - the website `cname` file contains `demo.guillaumedehaene.com` 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](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/verifying-your-custom-domain-for-github-pages).