Making a Website with GitHub/Quarto

There are many instructions for making Quarto websites or hosting on GitHub, but here is a list of instructions with links to other more detailed references as a roadmap to get started.

This isn’t comprehensive, but hopefully shares enough resources to get you started while clarifying some of the more confusing steps.

It can be a bit weird starting out and remember that you may be learning Quarto, git and GitHub (and possibly YAML, CSS and/or SCSS) all at once which is a lot!

So if you find it tricky, that’s normal, it’s nothing you can’t handle :)

Note: These instructions assume you want to create a personal/organizational website, not a website for a project or repository (although that can be similar in many steps)

Websites in General

It helps to have a brief overview of what it takes to get a website on the Internet. Generally there are three steps

1. Create the files

This step is where you create (by hand or with software), the actual html files which are the website. You can create these files and not put them on the Internet. Which means you have a website on your computer (local), which only you can see. This is great for previewing your website before putting it, or any changes, onto the Internet.

2. Serve the files

This is when you put (serve or host) your html files on the Internet. You need a server to serve or host the files and generally you go through an external company¹ to do this for you (i.e. a Hosting service, or GitHub).

3. Link a domain name

This step is often optional, depending how you are serving your website. If you use GitHub to serve your website, you will have a website address of https://yourgithubusername.github.io. If you want to buy (or really, rent) a domain name and point it to the website, then you can have a website address of something like https://your-domain-name.com (mine is https://steffilazerte.ca).

Quarto and GitHub

So if you want to make a website with Quarto and GitHub you will be creating the website files with Quarto (step 1) and serving the files with GitHub (step 2). You can optionally also decide to buy a domain name and link it to your website (step 3).

Step 1. Creating your Website with Quarto

Quarto vs. RMarkdown

You can create a website with RMarkdown or Quarto.

Quarto is essentially rMarkdown v2. If you love RMarkdown and don’t want to switch, use that, otherwise it’s worth using Quarto as it has many features not available in RMarkdown.

Basic Steps

• To get started, follow the basic steps for Quarto Websites
• Check out the various Website themes you can use
• Make sure you’re working in a folder (project or repository) called yourgithubusername.github.io

Fiddly bits

There are several different ways of hosting your site on GitHub, but the most straightforward way is to ‘render’ your site into a docs folder and then tell GitHub to serve that folder (next step).

By default your website is created in the _site folder, but you can change this by changing the output-dir option in the _quarto.yml (this is the file that defines your site options).

For example, I use output-dir: docs which tells R to create the website in a docs folder.

To preview your website, use quarto preview in the terminal (the website will automatically update with any future changes), or render your website and then open the index.html file inside the docs folder (you will need to re-render and refresh the page to see new changes).

Step 2. Serving your Website with GitHub

Once you have and like your website, you’ll need to push it to GitHub and then tell GitHub that it should serve your website (it won’t unless you tell it to).

• Push your website² to GitHub. For learning how to push/pull to GitHub, I recommend
  • Happy Git with R
  • Birds Canada’s “GitHub: A Beginner’s Guide”
• Once it’s on GitHub, you can tell GitHub to ‘serve’ your docs folder, I recommend
  • Quarto’s instructions for Render to docs
  • GitHub Pages Documentation

3. Link a Domain Name (optional)

Now you’ll have a lovely website hosted at https://yourusername.github.io. There is nothing wrong with leaving it at this stage, if nothing else, you’re making it really clear that you are badass enough to be able to create a website and serve it on GitHub.

However, if you would like to use your own domain name, you can also do that.

First you will need to buy (rent) a domain name.

I buy mine (steffilazerte.ca) from Webnames, a Canadian Domain Registrar, but there are many others. If you have one bundled with a webhosting service, you can always transfer it to another Domain Registrar if that works better for you.

Next, you will need to configure GitHub to work with this domain.

• Simplest³ is to follow GitHub’s instructions for Configuring an apex domain

In short, you will tell GitHub about your Domain and then tell your Domain Registrar to point to GitHub.

Examples

Here are examples of several websites I’ve made and host on GitHub. In particular, take a look at the _quarto.yml files as this is how the pages, navigation and themes are set.

• Steffi’s website
  • Served from the docs folder
  • Code: https://github.com/steffilazerte/steffilazerte.github.io
  • Site: https://steffilazerte.ca
• Westman Naturalists’ website
  • Quarto, no docs folder, uses GitHub Actions to publish
  • Code: https://github.com/westman-naturalists/westman-naturalists.github.io
  • Site: https://westman-naturalists.github.io
  • Interesting bits: This site uses a GitHub action to update the Events page everyday at midnight from a Google Spreadsheet.

Other details

BibBase

Because I hate updating things by hand which can be automated, I use BibBase to automatically list my Publications and Presentations in my CV by pulling them in from Zotero.

Using R to automate things

Again because I hate updating things by hand, I use R code to automate many lists on my webiste.

• I use code to create lists of presentation resources with links to the slides. I don’t love this setup and would like to fiddle it in future to be a) more attractive and b) simpler to work with.
• I use code to create the tables displayed in my CV (note that the actual data and some of the functions aren’t included in this repository)

Resources

• Quarto documentation
  • Quarto Websites
  • HTML Themes in Quarto
  • Publishing Quarto Websites with GitHub Pages
• GitHub Pages documentation
  • Creating a GitHub Pages site
  • Custom Domains
• Working with git and GitHub
  • Happy Git with R
  • Birds Canada’s “GitHub: A Beginner’s Guide”

Footnotes

1. You can have your computer do this for you, but then your computer needs be on and running (and serving) files 24/7 and requires a more complex setup.

2. You have to push the docs folder, but generally I recommend pushing all files except anything sensitive you need to keep private. This way you can share the love of how to create your own Quarto Website on GitHub!

3. In the sense that there are other, more complex things you can do, not in the sense that this is particularly straightforward.