Setting up a blog using quarto

Notes on how the site was set up. And how to blog using quarto.

How-to
Published

March 6, 2022

This is a minimal, living document to remind ourselves how we set up the blog, and how to write on it. We will update it as needed. It may turn out to be useful more generally, but the best place to look is the quarto site.

Folders and files

There are a number of files needed for a quarto blog project, as we can see by taking a look at the repository. The main ones are listed here.

Other files in the repository are needed for quarto to execute the python notebooks, github pages, etc.

Github pages CI

The website is re-built (on pushes) and deployed (on merge into main) using github actions, see workflow.

Commenting functionality

Provided by giscus, which links to github Discussions, see quarto docs and links.

Writing posts

  • All posts should be stored as .qmd files, indeed .Rmd and .ipynb are included in the .gitignore.
  • jupytext allows to link .ipnb and .qmd notebooks. This is set up in the .jupytext.toml file. One can also use jupytext --to ipynb index.qmd for individual posts.
  • Every post should have its own folder in the posts/ folder, as outlined in quarto docs.
  • Quarto allows to render the blog locally as one works on a new post (or any other changes) using quarto preview. This is live-reloaded whenever we save.
  • Contents of _freeze should be committed, as the CI does not rebuild the posts. This could lead to posts breaking if dependencies change, etc. and is advised against in the quarto docs.

NOTE: Any rendered content, in the docs/ folder, should not be pushed to the repository, but we cannot (simply) add it to the .gitignore, as this would break the CI which pushes the contents of docs/ to the pages branch.