GitHub template for Quarto website on Netlify

Use case

To enhance each of my research projects, I aim to create an all-inclusive compendium and share it through a captivating Quarto website. I am keen on constructing and deploying this website with the seamless integration of GitHub Actions and Netlify. By utilizing GitHub Actions, I can ensure that rendering and publishing processes are effortlessly triggered with every commit made to the remote repository on GitHub. To facilitate this, I rely on the powerful IDE called RStudio, which enables me to efficiently code the pipeline, including the creation of the Quarto website, setting up GitHub Actions, and establishing a connection with Netlify. Once implemented, any commit, regardless of the IDE used, will automatically build and deploy the website to Netlify. It would be delightful to utilize this as a template for all my future research projects.

Prerequisites

• The RStudio IDE (to code the pipeline)

• A GitHub account (to be able to use GitHub Actions)

• A Netlify account (to publish the website to)

Step-by-step guide

Here, the steps are given that you must follow to build a Quarto website for the use case. In the next section, you will see how to get the same results fully relying on Netlify instead of GitHub Actions. After that, it is shown how to use the GitHub template. Using this template, you do not need to manually perform this guide step-by-step each time you need a Quarto website as a starter.

1. Fire up RStudio and choose File → New Project… → New Directory → Quarto Website

2. Fill out the details in the panel, for example like in the figure below, and click on the Create Project button:

3. Add a .gitattributes file and change the RStudio line endings setting to None along the lines of my gist about line ending issues with Quarto.

   Important

   Step 3 does no longer apply. I added this step 3 to my original post to prevent GitHub Actions from failing due to hash issues caused by end-of-line character differences between operating systems (see my gist for more). However, this step 3 is no longer needed since the removal of the hash issue by this pull request.

4. Execute the quarto publish command for Netlify in the Terminal pane of RStudio:

   quarto publish netlify

   After you press Y to publish with you default account, this automatically creates a _publish.yml file in the local repository that looks like the example below, but with the appropriate id and url values for your site:

   - source: project
     netlify:
       - id: d1983ae8-da83-4431-928f-3debf80a02a5
         url: 'https://splendorous-bublanina-d544bb.netlify.app'

5. Add the following lines to the _quarto.yml file in order to make sure that code is only executed locally:

   execute:
     freeze: auto  # Re-render only when source changes

6. Fully re-render your site in the Terminal pane:

   quarto render

7. Add the output directory of your project to .gitignore:

   /_site/

8. Go to the Git pane of RStudio to commit the files created thus far to your local repository: Git → Commit pending changes → select all files → Stage all files → write a Commit message, for example ‘First commit’ → click the Commit button.

9. Execute this command in the Console pane of RStudio to push your local repo to GitHub:

   usethis::use_github(private = TRUE)

   This will create a private remote repository at GitHub. You may change the argument private to FALSE if you want the remote repository to be public right away, or change this manually in the settings section of your GitHub repository at some later moment.

10. Add GitHub Actions to your project by creating the YAML file publish.yml and save it to .github/workflows/publish.yml:

    on:
      workflow_dispatch:
      push:
        branches: main
    
    name: Quarto Publish
    
    jobs:
      build-deploy:
        runs-on: ubuntu-latest
        steps:
          - name: Check out repository
            uses: actions/checkout@v2 
    
          - name: Set up Quarto
            uses: quarto-dev/quarto-actions/setup@v2
    
          - name: Render and Publish
            uses: quarto-dev/quarto-actions/publish@v2
            with:
              target: netlify
              NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}

11. Configure your GitHub with the credentials required for publishing to Netlify. This is explained in the Quarto docs. In short:

    • find/create a personal access token at the Netlify applications page
    • go to the remote repository at GitHub → Settings → Secrets and variables → Actions → click on the button New repository secret
    • fill out the name (i.e. NETLIFY_AUTH_TOKEN) and value of the personal access token

12. Commit the publish.yml file and subsequently push your local repository (including the _freeze directory) to GitHub. As a consequence, your GitHub Actions workflow will start running and the website is automatically rendered and published to Netlify. Each subsequent (commit and) push will trigger the GitHub Actions workflow to start running in the same way.

The Quarto website that is described in this example was automatically named https://splendorous-bublanina-d544bb.netlify.app/] by Netlify. To remember it better, I renamed it to https://template-quarto-website.netlify.app/ in my Netlify account. I changed the url field in the _publish.yml file accordingly. You can visit the Quarto website at this latter URL.

The remote repository is located at https://github.com/pjastam/template-quarto-website/. Note that this repository is set up as a template, see the section “A versatile template”.

GitHub Actions

Throughout this guide, I have assumed the utilization of a GitHub Actions Runner to execute the job defined by the GitHub Actions workflow. Note that achieving the same outcome is possible without relying on GitHub Actions. More specifically, you can delegate the responsibility of rendering the website to Netlify itself, which seamlessly handles the entire process before deploying it to their servers. To follow this alternative approach, simply skip the last three steps (10-12) outlined in this how-to guide and add two extra files after adding the .gitigore file (i.e., after step 7). The files that must be added are a netlify.toml file with the following lines of code:

[[plugins]]
package = "@quarto/netlify-plugin-quarto"

and a package.json file with the following lines of code:

{
  "dependencies": {
    "@quarto/netlify-plugin-quarto": "^0.0.5"
  }
}

Finalize with committing all files to you local repository (step 8) and pushing your local repository to GitHub (step 9). Again, do not execute steps 10-12 in this scenario.

A versatile template

The remote repository that results from the steps described in this step-by-step guide is located at https://github.com/pjastam/template-quarto-website. To use it as a template repository for your Quarto websites, I have checked the Template repository box in the Settings tab of this remote repository. Furthermore, note that the two lines of code with the Netlify credentials (see step 3 of the step-by-step guide) are commented out (i.e. deactivated). In this way, people are guarded from mistakenly using these credentials instead of the Netlify credentials of their own site.

To actually use this template, there are 6 steps involved:

1. Use my template to create your new repository by clicking this button at the top of the remote repository at GitHub:

   

2. Fire up RStudio, choose File → New Project… → Version Control → Git and fill out the web URL of your new repository to clone it to your local environment. You can find this web URL at the top of your new repo at GitHub:

   

3. Delete the _publish.yml file from your local repository.

4. Execute step 4 of the step-by-step guide.

   Caution

   Before continuing with step 5, please double-check that the _publish.yml file in your local repository now contains your own Netlify credentials. Otherwise the workflow will never run the right way.

5. Execute step 11 of the step-by-step guide.

6. Execute step 12 of the step-by-step guide.

Your Quarto website will be up and running any moment.

What’s Next?

In this guide, I have created a Quarto website to be used as a research compendium.¹ However, the current content is rather limited for this use case. I plan to enhance it with essential compendium components and publish that repository on GitHub in the near future. You can use that as a reference template for your own research compendium, so stay tuned for updates!

¹ The Quarto docs about publishing on Netlify were a nice starting point for this how-to guide.