Creating a CAFRI Blog Post

CAFRI has a blog, cleverly named Acceptable Growing Stock, where we share internal documents and reports describing results small and large. 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.

Some concrete examples…

How to Create a Post

All of our blog posts are built using distill and rmarkdown which makes things quite simple. All you need to do is to create an Rmarkdown file with your code and text, and include the appropriate output format in your yaml header (see below). This should be done outside of the acceptable growing stock repo, inside another R project (either your own, or another CAFRI project). ‘Knit’ or render the file iteratively, until your local output is finalized. Then, you’re going to want to import the post to our distill blog.

To import the post you’re first going to need to be comfortable with git. Then clone the acceptable growing stock repo to your machine. Start an R session within the acceptable growing stock project, and run the following bits of code:

distill::import_post("<path-to-your-rendered-post.html>")
rmarkdown::render_site()

This might take a bit, as our blog has grown quite large. Finally, once the blog is fully rendered and you can preview that everything looks as it should (check git diffs as well), commit and push your changes to our blog. Go grab a coffee or take a walk, and when you come back you should see your post live on our blog.

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 our blog:

---
title: <your title here>
author
date
description
output:
  distill::distill_article:
    toc: true
---

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!!!