Template for Auto-Deploying Quarto-Book on GitHub with GitHub Pages

Editor’s Note: The author of this post has an affiliation with the GitHub Campus Advisors Program and sometimes receives free goodies from GitHub.

Background

For the last year and a quarter, I’ve been following the quarto project spear-headed by J.J. Allaire and Charles Teague. They describe quarto as:

an open-source scientific and technical publishing system built on Pandoc

Perhaps a better, albeit more simplified description is:

a multi-language implementation of RMarkdown-like reproducible reports with a lot more page layout control.

Why is the page layout control so nice? Well, we have side-by-side code chunks without needing custom styling across multiple formats for one!

::: {layout-ncol=2}
#### R

```r
my_list = list(1, 2, 3)
typeof(my_list)
```

#### Python

```python
my_list = [1, 2, 3]
type(my_list)
```
:::

With only that code chunk, we are able to generate the following: https://tutorials.thecoatlessprofessor.com/quarto-book-template/.

In any case, I’m excited to see increased levels of interest and support the project is receiving.

Action Design and Template

To that end, I wanted to deploy a quarto book on GitHub via GitHub Pages. (I’m not a fan of Netlify as they add another failure point and began placing caps on their services; but, they needed the restrictions to generate money!) Unfortunately, the quarto-dev/quarto-actions repository only includes a GitHub Action for installing quarto via uses: quarto-dev/quarto-actions/install-quarto@v1 by the wonderful Christophe Dervieux (cderv). Work is currently underway to incorporate a quarto render action; however, there seems to be a timeout.

As a result, I’ve created a GitHub Template Repository called coatless-tutorials/quarto-book-template. The repository contains a minimal viable textbook that is built using both R and Python code. For a more advanced set of options and a better starting template, consider following the Creating a Book - Getting Started section. Though, you will likely want to add the newly developed quarto-render action into your own repository’s .github/workflows folder to generate and auto-deploy the textbook.

The quarto-render action contains the following steps:

on:
  workflow_dispatch:
  pull_request:
    branches: [main, master]
  push:
    # only trigger on main/master branches, not on tags
    branches: [main, master]

name: quarto-render
jobs:
  quarto-linux:
    runs-on: ubuntu-latest
    env:
      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
    steps:
      # Download a copy of the repo
      - uses: actions/checkout@v2
      # Setup pandoc (might be included with Quarto action?) 
      - uses: r-lib/actions/setup-pandoc@v2
      # Setup R
      - uses: r-lib/actions/setup-r@v2
        with:
          use-public-rspm: true
      # Handle installing R packages from DESCRIPTION file
      #- uses: r-lib/actions/setup-r-dependencies@v2
      #  with:
      #    extra-packages: any::ggplot2, local::.
      
      # Download latest version of Python
      - uses: actions/setup-python@v2
      
      # Install python dependencies from requirements via pip
      #- name: "Install Python dependencies via Pip"
      #  run: |
      #    pip install -r requirements.txt

      # Grab a copy of quarto and render the document in all formats
      - uses: quarto-dev/quarto-actions/install-quarto@v1
      - run: |
          quarto render --to all
      # Deploy the rendered _book directory onto Pages
      - name: Deploy to GitHub pages 🚀
        if: github.event_name != 'pull_request'
        uses: JamesIves/github-pages-deploy-action@4.1.4
        with:
          branch: gh-pages
          folder: _book

For an up-to-date version, please see:

https://github.com/coatless-tutorials/quarto-book-template/blob/main/.github/workflows/quarto-render.yml

The template repository is rendered here:

https://tutorials.thecoatlessprofessor.com/quarto-book-template/