Setting up a quarto blog

Adding a blog within a quarto website

What am I trying to do?

My aim here is to set up a blog within an existing quarto website. I want the blog to be a sub-domain of the main site (zakvarty.com/blog) and for it to inherit the styling of that site.

It probably would have been easier to make the blog a sub domain (blog.zakvarty.com) and use two separate but matching style files to make those sites look coherent. However, I wanted to make the most of the built in search features on quarto websites and am a glutton for punishment.

Credit to Drew Dimmery, whose website I used alongside the quarto docs to work out how to get all these pieces working together.

Steps

1. Create a subdirectory of the website called blog/. This has sub-folders for each blog post and will contain the files of metadata that are common to all blog posts (e.g. default settings for YAML headers information and a bibliography file).
2. Create a listing page called blog.qmd in the root directory. This will become the blog “landing page” and what we will point to from the website header.
3. Add a “Blog” header item to the _quarto.yml file for the website and set the link: for this to be blog.qmd
4. Added a simple example post to the blog/ directory. See for example my hello-world post.
5. Adjust the default YAML parameters for the blog posts by making the file blog/_metadata.yml. These default values can be overwritten by specifying them again in the YAML header at the top of any individual post. For examples of what you might want to include see my file or the projects section of the quarto docs.
6. Add a simple bibliography file, called library.bib or similar to the blog/ directory. Set this as the default bibliography file for each blog post by adding bibliography: ../library.bib to blog/_metadata.yml.
7. (optional) Create a post template so that you don’t have to memorise header fields.
8. Set your “Hello, World!” and template posts to have draft: true in their headers. This will prevent them from showing up on your website.
9. Set your “Hello, World!” and template posts to have freeze: true in their headers. This will prevent any code in them from re-running each time the website is rendered.

Freezing the code within posts will improve the build speed, as well as make the website more stable and portable. See the quarto docs on freezing posts for more details. My current plan is to have this as false by default and change to true on publication of each post.

Checking that references work

I have set up a single bibtex file in which to store references for all posts. This lives in the blog/ directory and is set as the default bibliography parameter for each post in the file blog/_metadata.yml.

This is an in-line reference to Wan et al. (2020) written as @citationkey. Parenthetical references, such as (Wan et al. 2020), are written using [@citationkey]. These can be strung together by separating each citation key with a semicolon, for example (Wan et al. 2020, 2020).

To let people know the license your work is under and how they should cite your blog posts you can use the appendix-style argument. This can be added to the YAML header of individual blog posts or you can specify a default value in blog/_metadata.yml. There are three options for this parameter:

• default does some nice formatting and makes the text a bit smaller than the rest of the article;
• plain matches the style of the rest of your post;
• none does not add any citation details to the end of your post.

I’m currently using some pretty hacky CSS to style this website so am limited to the latter two options for now. In the process of writing this article I stumbled across some neat SCSS that I hope will fix this issue that I have made for myself! [Update: I changed to SCSS and this is now fixed!]

Note: When adding references to your posts, make sure that the site-URL field in your website’s quarto.yml does not have a trailing slash - this will be copied into the reference and break the links.

References

Wan, Phyllis, Tiandong Wang, Richard A Davis, and Sidney I Resnick. 2020. “Are Extreme Value Estimation Methods Useful for Network Data?” Extremes 23 (1): 171–95.