About a year ago, I wrote my first ever blog post ~ about blogging ~ and tbh I’m a little embarrassed that this is only my third post here (does it count that I have ideas for blog posts squirreled away at least?? ). Regardless, you should trust me1 when I say that blogging is a great exercise for you to practice as regularly as you can – it can help you to:
Rather than repeat more content here, take a peek at my first post, which touches on more reasons why you should blog and provides some ideas on how to structure your blog posts. Before jumping into things, I’ll leave you with one last piece of advice from @drob:
When you’ve written the same code 3 times, write a function
When you’ve given the same in-person advice 3 times, write a blog post
Our Master of Environmental Data Science (MEDS) students created the bones of their Quarto websites a couple months ago, and more recently took a little dive into website customization using Sass & CSS. For anyone who’s looking to get started on their website-building journey, feel free to explore the following resources:
II. What’s the difference between a website and a blog?
If you’ve spent some time poking around the official Quarto documentation, you may have noticed instructions for creating either a Website or a Blog – but what’s the difference? Not much, aside from the initial structure:
When you create a new Quarto website, it’ll look like this (it has a traditional landing (i.e. ‘Home’) page and no incorporated blog)…
… while a new Quarto blog will look like this (with a listing page as your landing page)
A Quarto Blog is a type of Quarto Website – according to the Quarto documentation, you can create websites that consist of just a single blog (like the above right-hand example), websites that have multiple blogs, or you can add a blog to a website that contains other content (which is what we’ll be doing today).
III. Adding a blog to your personal Quarto website
TL;DR: A couple of steps are required for setting up your blog, but generally speaking, you’ll need:
a folder (i.e. subdirectory) to hold all of your individual blog posts – I called my folder posts (though the name is up to you). I also (optionally) added a _metadata.yml file to this folder which includes some formatting and configuration options that will apply to all blog posts in this folder
a listing page, which lists all of your blog posts for viewers to browse and click through – this is a .qmd file that you’ll add to your website’s navbar by including it in _quarto.yml
blog posts! Your listing page will be blank until you actually add your first blog post
Let’s create those together now.
Create a /posts folder: Open up your Quarto website project (I find it easiest to do this in RStudio) and make sure you’re in your root directory. Here, we’ll create a new subdirectory, called posts (you can call this whatever you want), where all of our blog posts will eventually live. To do so, you can either (a) click on the add folder button, , in the Files pane, or (b) in the RStudio Terminal, run mkdir posts.
Optional:Add a _metadata.yml file to /posts: While not required, a _metadata.yml file can make your life easier if you want certain options to apply to all blog posts that you create. Create this one of two ways: (a) In the RStudio Terminal, run cd posts to move into that directory, then touch _metadata.yml to create the file, or (b) click into the posts/ folder in the Files pane, then click Blank File > Text File > type _metadata.yml > click OK. Open your _metadata.yml in the Source pane to add options. I like these options2, but it’s entirely up to you what you want to include (if anything at all):
_metadata.yml
# options specified here will apply to all posts in this folder# prevents posts from re-rendering unless explicitly told to do so (for more, see https://quarto.org/docs/projects/code-execution.html#freeze)freeze: true# enable banner style title blocks (see https://quarto.org/docs/authoring/title-blocks.html)title-block-banner: true
Create a listing page: A listing page is a page with content that is automatically generated from a list of documents – in this case, that would be a list of blog posts – and looks something like this (or check out my blog’s listing page):
An example listing page from the MEDS Community Blog showing multiple blog posts. While the MEDS website/blog is created using {distill}, you can expect something super similar. Quarto has multiple listing page layout options (default – which looks similar to the MEDS blog, grid, table) for you to explore
To create a listing page, add a posts.qmd file to your root directory. First, click on the R Project icon, , in the Files pane to jump back to your project’s root directory. There are a bunch of ways to create a new .qmd file, but one easy way is to choose File > New File > Quarto Document…. Below, I give mine the title “My Blog” when prompted (this name appears at the top of your listing page), then saved it as posts.qmd (but you can choose whatever title and/or file name you’d like).
Configure your listing page: Specify how you’d like your listing page to be arranged by updating the YAML section of posts.qmd. There are a variety of options that you can specify. Below are just a few, but be sure to check out other options:
posts.qmd
---title:"My Blog"listing: contents: posts # all Quarto docs in the `posts` directory will be included on your listing page type: grid # or `default` or `table`; each type has its own set of yaml options to include sort:"date desc"# can also sort on more than one field categories: true # allows you to sort posts by assigned categories ---
Add your listing page to your website’s navbar: Update _quarto.yml with your new listing page to add it to your site’s navbar:
_quarto.yml
# ~ parts of `_quarto.yml` omitted for brevity ~website: navbar: title: myWebsiteTitle right:- href: index.qmd text: Home- about.qmd- posts.qmd # add your posts.qmd file to your navbar!
Preview or Render your website: Make sure your listing page shows up by previewing (I typically run quarto preview in the Terminal) or rendering (click the Render button in the Build tab in RStudio) your website. You should have something that looks like this (we haven’t created any posts yet, so it’ll be empty for now):
IV. Add a blog post to your blog
Now that you have your listing page set up, we can start populating it with blog posts. Repeat the following steps each time you want to add a new post.
Create a subdirectory inside your posts/ directory: To stay organized, I usually name mine YYYY-MM-DD-short-post-description. This folder name will also become the slug for your published post.
Inside your new subdirectory, create an index.qmd file. The name here is important! It must be called index.qmd. Your file path should look something like this: myWebsite/posts/2022-10-24-my-blog-post/index.qmd. This file is your blog post. Write all your content here!
Configure your blog post: You can add a variety of different options to the YAML section of index.qmd. Here are my go-to options:
posts/2022-10-24-my-blog-post/index.qmd
---title:"blog post title"description:"blog post description (appears underneath the title in smaller text) which is included on the listing page"author:- name: Samantha Csik url: https://samanthacsik.github.io/ orcid:0000-0002-5300-3075 affiliation: Master of Environmental Data Science Program @ The Bren School (UCSB) & The National Center for Ecological Analysis & Synthesis affiliation-url: https://ucsb-meds.github.io/date:10-24-2022categories: [Quarto, R, MEDS] # self-defined categoriescitation: url: https://samanthacsik.github.io/posts/2022-10-24-my-blog-post/image: preview_image.jpgdraft: false # setting this to `true` will prevent your post from appearing on your listing page until you're ready!---
Some notes on the above options:
You should include a title, but don’t necessarily need a description (although I think they’re nice to have!). Both of these fields will appear on your listing page.
You can include more than one author – see this post and source code as an example.
You may include as many self-defined categories as you’d like. Make sure that your spelling/capitalization/punctuation is consistent across blog posts should you apply the same categories to multiple posts.
Adding the citation option automatically generates both a BibTeX citation and reference for your blog post, and adds them to the bottom of your post.
Include an image (or gif) to add as a preview image, which will appear on your listing page alongside your post. Your image should live inside your post’s subdirectory (e.g. mywebsite/posts/2022-10-24-my-blog-post/preview-image.png).
Set draft: true while you’re still working on your blog post to prevent it from showing up on your listing page, site map, or site search (it will still be available at a searchable URL). When you’re ready to publish, just remove draft: true from your YAML (or set to false), then render your post.
A grid-style listing page featuring one blog post with a preview image, title, three categories, description, author, and publishing date
An example blog post, with a banner-style title block
If things aren’t working as expected, double check your repository structure – it should be organized similar to this:
V. Some additional authoring features to explore
Blog posts are just Quarto documents, meaning you can combine prose, code, and embedded outputs all in one place, just like you would in any other .qmd file (which makes your blog the perfect place to create data science/programming tutorials both for yourself and others ). If you’re looking for additional ways to enhance your posts, read on below:
Adding footnotes
There are multiple ways to include footnotes throughout your blog posts:
Use the [^#] syntax to denote where you would like a note to be inserted. Write your note somewhere below following the [^#]: your note here syntax. For example:
I am going to insert a footnote here[^1].[^1]: Here is the associated footnote, which will appear at the bottom of my document in a "Footnotes" section.
Alternatively, you can write your notes inline to avoid having to use identifiers (e.g. [^#]). For example:
I am going to insert an inline footnote here^[Here is my inline footnote].
You can also add footnotes that include multiple paragraphs. See the source code for this blog post and take a peek at footnote #2 for an example on how to do so (or check out the Quarto documentation).
All footnotes will appear in a “Footnotes” section that is automatically generated for you.
Creating a bibliography and adding citations
Quarto supports the use of bibliography files for citing works throughout your blog post. There are a number of ways to do this, but so far, I’ve found creating a BibLaTex database to be relatively straightforward. This database takes the form of a plain-text .bib file where we can store all of our bibliographic information. That information needs to be encoded in a particular way (more on that below). Follow these steps to cite works in your blog posts:
First, create a .bib file in the folder containing your blog post (e.g. myWebsite/posts/2022-10-24-my-blog-post/references.bib) using the touch command in your RStudio Terminal or using the Blank File > Text File button in the Files pane. I called mine references.bib, but the name is up to you.
To use your references.bib file, you’ll need to add the bibliography option to your blog post’s YAML:
---title:"blog post title"# ~ additional YAML options omitted for brevity ~bibliography: references.bib---
Next, we’ll want to add some references. These take a particular format that generally looks like this (the number/types of fields included may vary):
references.bib
@type{key, author = {LastName, FirstName}, title = {Title of work}, date = {YYYY} url = {https://url.com}, langid = {en}}
where type can be manual, book, article, misc, etc. (all case-insensitive) and key is the citation identifier used for inserting in-text citations (we’ll get there soon).
There may be instances where you want to cite a resource that already has a BibTex citation available for you to copy over to your references.bib file (e.g. this blog post). For most resources, however, you’ll need to construct your own. You can do this manually, or with the help of a BibTeX reference generator (Googling will yield plenty of options, but zoterobib is a great place to start. Note that you may have to make some manual adjustments). Check out my references.bib file for this post as an example.
Now that you have BibTex references in your .bib file, you can start adding in-text citations. These generally take the form [@key] (but read more about Quarto citation syntax here). When you add an in-text citation, Quarto will automatically add the reference to the bottom of your blog post under the “References” section.
To give one final concrete example, let’s say I want to cite my first (ever) blog post from last year. I can copy the BibTeX citation from the bottom of the post and paste it into my references.bib file:
@online{csik2021, author = {Samantha Csik}, title = {Why Create Presentation Slides about Blogging When You Can Just Blog about It Instead?}, date = {2021-09-24}, url = {https://samanthacsik.github.io/posts/2021-09-21-distill-blogs/}, langid = {en}}
I can now add an in-text citation using the [@csik2021] syntax here (Csik 2021). Once cited, it will appear in my References section at the bottom of this post.
That wasn’t so bad, right?? What if I told you there was an even easier way to add citations….Start by popping over to RStudio’s Visual editor, if you’re not already there (you should see buttons for working in either the Source or Visual editor in the top left corner of your source pane), and follow the steps below:
Place your cursor where you’d like to insert a citation, then from the Insert drop down menu, select Citation.
A new window will pop open with a number of different options for inserting citations. If you’ve already created a references.bib file, it will appear under the My Sources and Bibliography sections. You can choose any of your existing references to insert an in-text citation from or choose another option, like inserting a citation based on a DOI (!!! I can’t tell you how awesome I think this is !!!). Once you add an in-text citation based on a DOI, the BibTeX reference will automatically be added to your references.bib file, as well as to your references list at the bottom of your post. If you don’t yet have a references.bib file, one will automatically be generated for you. LIKE SERIOUSLY?? SO FREAKIN COOL.
Okay, back to being chill…
Article layout
Quarto also supports a number of different page layout options to further customize the appearance of your posts. Explore different ways to position elements on your page, including embedding outputs, captions, references in your page margin (one of my personal faves…despite the fact that I don’t have any here in this post).
VI. A note on adding an additional blog (or more) to your site
You aren’t limited to just one blog/listing page! Repeat Part III to add a second listing page + content to your website. My personal website contains three listing pages – one called posts (aka my actual blog), one called talks & workshops, and one called projects. Explore the GitHub repo to take a peek at the file structure and source code.
VII. Blogs to follow (+ one post from each that I’ve particularly enjoyed)
There are tons of awesome data science bloggers out there – here are just a few that I’ve enjoyed, but get out there and start exploring others for yourself!
Also note: I’ve included one blog post from each creator and added citations. Check out the source code for this post if you’re looking for additional examples on how to do it.
Creating a blog with Quarto in 10 steps, by Beatriz Milz walks through the steps of setting up a new Quarto Blog project. She also details how to set up giscus to enable comments on your blog posts, which is something I’ve been eager to try myself!
Okay, you don’t just have to trust me. Lots of data scientists advocate for blogging as an important skill and communication tool. Check out this blog post by David Robinson to start.↩︎
The freeze option: Setting this option to auto will only re-render posts when you make updates to the source files (as opposed to re-rendering them each time you Render Website – this can save time, particularly if you have computationally-heavy content in your blog posts). If you set this option to true, posts will never be re-rendered (even if you’ve made changes to the source files). If you use this option, you’ll need to Render individual posts whenever you make changes to their source files before you Render Website, otherwise your updates will not appear.
The title-block-banner option: Setting this option to true will enable a banner style title block (where the title, subtitle, description, and categories are all positioned inside the banner) for all posts.↩︎
Citation
BibTeX citation:
@online{csik2022,
author = {Csik, Samantha},
title = {Adding a Blog to Your Existing {Quarto} Website},
date = {2022-10-24},
url = {https://samanthacsik.github.io/posts/2022-10-24-quarto-blogs/},
langid = {en}
}