Making a Website with GitHub/Quarto


August 23, 2023

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

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 generally1 you go through an external company to do this for you (i.e. a Hosting service, or GitHub).

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 with a folder (project or repository) called
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, or, render your website and then open the index.html file inside the docs folder (in this case you will 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).


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.



  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↩︎