Blog Instructions

news
Author

JY

Published

December 20, 2025

Modified

January 3, 2026

Purpose

This page is for explaining how to operate the BC Beer Stats Blog, including instructions for composing a new blog post.

You should NOT be seeing this page via navigation. If you are, something is wrong with the site navigation setup. It will still be rendered and accessible but should not be in navigation, as it is not for public. (It may show up in some preview modes but not in production.)

Components of the Blog Site

This blog works slightly differently than a standard Quarto blog site, because it is embedded within a larger site that is not a Quarto project. The way this works is that:

  • blog-src/: main folder where blog content is developed and stored:
    • blog-src/ folder also has the _quarto.yml file that defines the blog site configuration.
    • blog-src/ also has a _metadata.yml file in the posts/ folder that defines metadata for all blog posts.
  • blog-src/posts/: folder where individual blog posts are stored.
    • each blog post is in its own sub-folder under posts/ with an index.qmd file for the post content.
  • blog-src/img/: folder for any images that are used across multiple posts or general blog images (e.g., banner images, icons, etc.)
  • blog-src/about.qmd: page for author bio/profile (not linked in navigation
  • blog/: When the site is rendered, content in blog-src/ is built into static HTML files and placed into the /blog/ folder, which is then served as part of the overall site. NO NEED TO TOUCH ANYTHING IN THIS FOLDER as it is all automatically generated.
  • Format/layout for blog hm page is defined in the blog-src/index.qmd file, particularly the listing section of the YAML header.
    • blog-overrides.css file is used for further customization of blog appearance. it’s called ‘blog-overrides.css’ because it overrides Boostrap theme styles for Quarto.
  • Format/layout for blog posts is defined in the blog-src/_quarto.yml file with further customization:
    • yaml header for each post define header components and some additional layout options.
    • blog-post-overrides.css file is used for further customization of blog post appearance.
  • Other supporting files:
    • _common.R: load this file with source(here::here('blog-src','_common.R')) in the first code chunk at the top of blog post. it loads required packages, functions from the files in R/ folder, and potentially other commonly-used settings, all in one place.
      • update with new packages as they arise, or other common functionality
    • R/utils-data.R: functions for fetching data from database as well as common types of manipulations, creation of commonly-needed data frames. based on functions used in bc-lmr-data-products project.
    • R/utils-viz.R: functions for standardizing, simplifying, or otherwise creating settings for data visualizations that apply widely in posts.

How to operate the BC Beer Stats Blog

Rendering entire site:

To render entire quarto site: (good to do before major commits)

  1. Terminal > go to ‘blog-src’ directory
  2. Terminal > quarto render

Preview vs Render:

  • each .qmd doc has a ‘Preview’ button in top left of window
  • easy to render the specific doc and see what it will look like
  • quarto render does the same thing for ALL .qmd files at once (along with all supporting files)

To add a new blog post:

  1. create a new folder under blog-src/posts/ with a unique name (e.g., my-new-post)
  2. inside that folder, create an index.qmd file for your blog post content.
    1. can use existing blog post, probably most recent, as a template.
    2. refer also to blog-src/posts/demo-post-with-code for examples.

yaml header

Contents for the yaml header include:

  1. title / subtitle
  2. author
  3. date: hard-coded date
  4. date-modified: “2026-01-03” to automatically update when changes made
  5. categories: brackets, comma separated [cat1, ca2]; avoid excessive list of unique categories
  6. description-meta: for SEO
  7. draft: true (until ready to publish)
  8. image: image to use for thumbnail on listings page; if nothing specified, will take first image in post
  9. html: settings for html - not sure these always work
    1. example

_common.R

  1. source _common.R in first code block

    1. get standard packages, functions all in one go:

  2. Carry on with your post!

Getting BC Beer data

  1. To get BC Beer data for your post, you can run functions in R/utils-data.R
    1. utils-data.R functions will be available after you source _common.R

Images

  1. Store any images for the post in the same folder - if there are lots, may want to create img/ folder, but that is optional.
  2. Insert images where you want with the tool bar icon or insert > image in Visual mode
  3. captions:
    1. in the image dialog, add captions, like Source information.
    2. in attributes > style may want to add font-size: 0.8em;

Tables

  • gt pkg is good for post tables
  • see posts/demo-with-post-code for examples, along with other posts