Rendering documents

You can render documents such as Quarto¹, R Markdown, and Jupyter notebooks and publish the outputs with GitHub Pages. Analysis notebooks, scheduled reports that crunch data from external databases, and documentation websites for software can all be published automatically with GHA & Pages.

Take a look at the example quarto document: quarto-report/notebook.qmd². Let’s write a workflow to render this document and publish it to the web:

.github/workflows/render-quarto.yml

name: render quarto reports

on:
  workflow_dispatch:
1  push:
    branches: main
    paths:
      - "quarto-report/**"
      - ".github/workflows/render-quarto.yml"

2permissions:
  contents: write
  pages: write

jobs:
  render-quarto:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

3      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2

4      - uses: r-lib/actions/setup-r@v2
      - uses: r-lib/actions/setup-r-dependencies@v2
        with:
          packages: |
            any::ggplot2
            any::palmerpenguins
            any::rmarkdown

5      - name: Run R script
        run: |
          print("Hello, world!")
        shell: Rscript {0}

6      - name: Publish to GitHub Pages (and render)
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages
          path: quarto-report/
7        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

1: Run this workflow on pushes to main only if files in quarto-report/ are changed or this workflow file changes.
2: Set the permissions to allow this workflow to write content to the repo and github pages. These permissions are disabled by default.
3: Install Quarto.
4: Install R and a few R packages.
5: You aren’t limited to only bash in run steps. You can set shell to run other scripting languages too! Rscript {0} means the contents of run will be passed to Rscript at runtime.
6: Render the quarto project in quarto-report, push it to the gh-pages branch, and publish it to github pages.
7: Pass the default GitHub Token with elevated permissions to the quarto publish action, so it will be able to write content to the repo and github pages.

Before you can use this workflow, we’ll need to first manually publish it to GitHub Pages.

quarto publish gh-pages quarto-report/

Once this finishes, the rendered report will be available at https://USERNAME.github.io/REPO (replace USERNAME with your actual GitHub username and REPO with your repo name, e.g. gh-actions-sandbox.)

The rendered report. View it at `https://USERNAME.github.io/REPO`.

Now, add the GHA workflow to your repo and it will keep your website up to date.

The first time this workflow ran, it took several minutes to complete (here, 6 minutes and 30 seconds). The main bottleneck occurs when installing R packages.

The setup-r-dependencies step took 5.5 minutes to complete

However, the setup-r-dependencies action caches the R packages³, so subsequent runs are significantly faster.

In the second run, the runtime reduced dramatically to 1 minute 16 seconds total

Take a look at the GitHub Docs for more information on caching dependencies to improve workflow runtime.⁴

Footnotes

Documentating Your Analysis with Quarto: https://bioinformatics.ccr.cancer.gov/btep/classes/documenting-your-analysis-with-quarto ↩︎
This document was adapted from an example in the Palmer Penguins documentation https://allisonhorst.github.io/palmerpenguins/articles/examples.html ↩︎
See the docs for r-lib’s setup-r-dependencies action for more information: https://github.com/r-lib/actions/tree/v2-branch/setup-r-dependencies ↩︎
Caching dependencies to speed up workflows: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows ↩︎
GHA worfklow for this very website https://github.com/kelly-sovacool/gh-actions-demo/blob/main/.github/workflows/docs-quarto.yml ↩︎

More workflows for rendering documents

Footnotes