Creating a Blog Post

This lab manual has a section for blog posts, which are sometimes also included on the pages of specific projects. This document walks through how to create blog posts and new blog feeds within this book.

We want to emphasize that this is an internal blog, for sharing among lab members and collaborators, since many posts only provide limited context and the results therein are often preliminary. As a result, we only send links to materials on this blog to CAFRI members and people who work closely with CAFRI. If you have questions about who you can share blog posts with, feel free to ask Colin, or another lab member.

When to Post

There are no real rules about what gets posted on the blog. We tend to add posts when we want to share results with other CAFRI members, or want to be able to refer back to some interim results later, but there’s nothing “too small” to merit a blog post. If your post might be useful to many people, or might be relevant in the long term (and isn’t just interim results), consider adding it to the lab manual either in addition to or instead of a blog post. Keep in mind that while we do only send links to the blog internally, anyone on the internet can technically see these posts, and as such the blog is not a good space for confidential materials.

  • Make these examples of blogs hosted on this site, not AGS

Some concrete examples…

How to Create a Post

All of our blog posts are built using Quarto, just like the rest of the book.1 Because of that, the place to start learning about how to create a post is the Contributing section of this book.

In short, all you need to do is to create a Quarto file with your code and text, and include the appropriate sections in your YAML header (see below). Save that file in the correct space in the book repository – blog posts are organized into sections based on the folders the post lives in. For instance, the blog for the AGB project is made up of posts stored in projects/agb-blogs. In order for your post to get included in the right project, just save the .qmd file in the corresponding folder! You can see an example in projects/agb-blogs/2023-03-14_testing.qmd, rendered at this link.

To preview your blog post, render it like any other document (through the “render” button at the top of the pane in RStudio, or Ctrl + Shift + K). A preview should open in a web browser.

To generate a preview of the book (with your blog), run quarto render in the terminal inside the lab manual repository, or quarto::render() in an R session with the lab manual as the working directory. When this finishes, you can investigate the _site directory to see the rendered version of the website. For instance, open _site/index.html in a web browser to see the homepage of the website.

Once you’ve confirmed both your post and the book look good, you’re ready to commit your blog and push the changes! You should commit both your .qmd and, if your blog post involved running any code, any changes to the _freeze folder (as well as any other changes you may have made). You shouldn’t need to commit the _site folder, as the website gets built automatically when your PR is merged.

How to Create a New Blog Section

If your post doesn’t fall into any existing blog section (like how the blog for the AGB project is made up of posts stored in projects/agb-blogs), feel free to create a new blog section.

To create a new section, first create a new folder and save your .qmd file into that folder. Then add the path to your new folder to the list in blog-posts.qmd, under the contents key:

---
listing:
  id: blogs
  contents: 
    - projects/agb-blog
    - your/section/here
---

Note that the paths are relative to the blog-posts.qmd file.

If you want to also list blog posts in this section on another page in the manual, you’ll need to add a listings section to that page’s YAML. For instance, the projects/agb.qmd page includes this in its YAML header:

---
listing:
  contents: agb-blog
  type: table
---

Note that the paths are relative to your project’s .qmd file – so here, we don’t provide the projects/ part of the path, because agb.qmd is already inside the projects folder.

It’s nice, but not required, to also add a subheading (like ## Blog Posts) to the end of your project’s .qmd file, so that the list of blog posts will be slightly separated from page content.

Including Images

A key reason for adding a blog post is to share intermediate figures and results with collaborators. This is great, and you should do it! However, every figure you add will wind up increasing the size of the lab manual, which might eventually wind up slowing down how long it takes to clone and build the manual overall. To keep the overall manual small, please:

  • Try to keep all files in your commit < 2 MB.
  • Save your images in efficient formats; SVG for vector drawings (scatterplots with < a few thousand points, line graphs, etc), PNG or JPG for maps and other extremely complicated graphs. Note that figures generated by R code in the manual will be SVG by default. If you’re generating a map, use #| dev: png (or if you have ragg installed, #| dev: ragg_png) at the top of your chunk to save it as a PNG instead.
  • Save your images at big-enough sizes. Figures generated by R code will default to 7 inches wide and 192 DPI, which is perfect for web images; you should probably use the same settings.

When you create a pull request that touches PNG or JPG images, a CI job will attempt to optimize those images in order to make the website more efficient. If it makes changes, please use the “squash and merge” option to merge the PR, in order to collapse the entire PR into a single commit; this will help keep the git repo smaller.

What to Include in Your Post

YAML fields

You need to include the following fields (feel free to copy this stub) in the markdown yaml header for your post to be properly formatted in the blog:

---
title: "Testing blogs in the Quarto book"
description: "A placeholder post"
author:
  - name: Mike Mahoney
    url: {}
date: "2023-03-14"
---

Please do not use any magic keywords for the date field (so no today, no last-modified, only date strings in ISO-8601 YYYY-MM-DD format).

You can also experiment with any of the other options for HTML documents. Some of these might not play nicely with the rest of the website; caveat emptor!

General Information

While we usually don’t include all of the background context for a set of results in a blog post, you should provide some. Specifically think about including the following:

  • A high level description of the post. If it’s short you can include it in the description yaml field (above), but you might want to have a separate section briefly summarizing what’s in the post and why it is important.

  • Links to your code (if applicable), or papers, or other resources that were used in the creation of your post.

  • A "Changes since last iteration" section is often helpful if you are iteratively posting, with a link to your previous iteration, and a description of what you have added/removed/changed in the new post.

  • Captions for figures and tables!!!

Acceptable Growing Stock

In the past, CAFRI blog posts were hosted at Acceptable Growing Stock.2 We no longer recommend using this blog for new posts,3 and encourage all new blog posts to be added to the lab manual.4 If you for whatever reason do still need to add to the old blog site, instructions are at this link.

Footnotes

  1. If you’ve ever used R Markdown, a useful mental model is “Quarto is R Markdown with slightly different YAML structure”. If you haven’t, more than half of that sentence was gobbledygook.↩︎

  2. Get it? Get it?↩︎

  3. Though old posts won’t be removed.↩︎

  4. Main reasons: 1) distill, the package powering that blog, is largely abandoned and most of our other workflows are moving from R Markdown to Quarto anyway; 2) We stored rendered HTML rather than source code, making the repo huge and a pain to work with while also making it so we couldn’t easily find the code that generated a post, edit posts, or move them to new platforms; 3) We’re aiming to have more of a “single source of truth” moving forward, specifically on this website.↩︎