Welcome

Notes to self
Over Christmas I decided to dig out old articles and speeches etc and put them online. For fun, I did it in Quarto, with an automated CI/CD pipeline. Here’s a dull description of how…
Published

January 1, 2024

Setting up a Quarto blog on Github

Quarto Logo

Useful resources are Github’s Pages setup guide and the Quarto’s Github Pages guide

Or you could follow these steps which condense the bits that mattered to me.

Broadly we’re trying to create a blog that can work with github-pages, or with that and Quarto - to have some options.

  1. On Github, make a new repo called <username>.github.io - pick a .gitignore template (e.g. the Python one)

  2. Navigate to an empty directory on your machine and run the following:

git clone https://github.com/<username>/<username>.github.io
cd <username>.github.io
  1. Tell Github we don’t want to use Jekyll thank you

touch .nojekyll

  1. Append ignores for built site so we don’t check it in to the repo as that’s annoying

echo -e "/.quarto/\n/_site/\n" >> .gitignore

  1. Make a default Quarto blog and push it to the repo
cd ..
quarto create project blog <username>.github.io
cd <username>.github.io
git add .
git commit -m "Commit default Quarto blog"
git push # may trigger GCM
  1. Check to make sure git is clean

git status

  1. Now create a gh-pages branch, initialise it and then flip back to main
git checkout --orphan gh-pages # switch to gh-pages
git reset --hard # make sure all changes are committed before running this!
git commit --allow-empty -m "Initialising gh-pages branch"
git push origin gh-pages
git checkout main
  1. Publish once manually

quarto publish gh-pages

  1. Then create the Github Action per the instructions on the Quarto page. It’s just creating a file in .github/workflows called publish.yml with the following contents. The magic with the curly brackets automatically populates with a secret when a Github machine runs it. Which is cool.
on:
  workflow_dispatch:
  push:
    branches: main

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

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

      - name: Render and Publish
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  1. With any luck your blog should now be visible at https://<username>.github.io/ and any changes you push to the repo should automatically appear on the published website after some minutes.