Adding blog posts

Okay, this actually includes more info than just instructions on how to add blog posts to the new Openscapes Quarto website...but it seemed like a reasonably place to put all this information (at least for now!).

Porting blog posts from blogdown to Quarto

After some brainstorming about how to automate porting blog posts from the original blogdown site to the new Quarto site, and some initial (not-so-successful) attempts at actually figuring it all out, I (Sam Csik) decided to port posts by hand. Surprisingly, this turned out to be a pretty fast process. Here's how it worked:

1. I cloned the website repo and grabbed the content/blog/ folder, which contains all blog posts (in the form of .md files). I moved this folder to my Desktop and renamed it /TODO (the name is not super important)
2. I created a second folder called /DONE (again, the name here is not important)
3. I opened both these folders side-by-side in Finder, alongside RStudio with my local website-new repo. In RStudio's Files pane, I opened the website-new/blog folder
4. Working from the top, I double-clicked on a blog post file in the /TODO folder (let's say the post called mentor-coach.md), which will open it in RStudio. I used the keyboard shortcuts, Cmd + A, followed by Cmd + C to highlight then copy everything in mentor-coach.md to my clipboard.
5. In RStudio's Files pane, I'd use the Create a new folder button to add a folder. I named folders using the following convention: YYYY-MM-DD-short-name, which is a combo of the date found in the .md YAML + the name of the .md file itself. (e.g. /2023-05-18-mentor-coach)
6. I'd then open this new folder inside RStudio's Files pane, then use the Create a new blank file in current directory button to add a Quarto Doc. I'd name this new file, index.qmd.
7. index.qmd is automatically opened in the RStudio console when created. I'd then paste the contents from my clipboard into this new file.
8. Some minor adjustments to the YAML were necessary: (a) deleting the tags option so that all keywords were combined under the categories option (see more about categories below), (b) changing the banner option to image (c) updating the file path to the image (see #3 in this section below for more details).
9. Once complete, I moved the .md file from /TODO to /DONE, then repeated with the next post.

Blog organizational structure

A roadmap of the website-new repo, indicating where all blog-related files should live:

Blog post listing page

blog.qmd generates the listing page, which is linked in the website's navbar:

Here, you can control the general appearance/layout of the listing page (e.g. where this listing pulls posts from, how posts are sorted, what information is displayed on the listing page, etc.). Explore the Quarto documentation to learn more about listing options.

Home page listing

There's also a "mini" listing on the landing page, which displays the most recent nine blog posts (across three pages):

This too will be automatically updated when a new blog post is added. Note: it appears as though blog posts must be written in .qmd files for them to appear here (.rmd files weren't showing up) -- this may have been user error, but be mindful. Configuration for this mini listing is done in the YAML of index.qmd.

Adding a new blog post

1. Create a new subdirectory (folder) inside the blog folder and name it using the following convention: YYYY-MM-DD-short-description (e.g. /blog/2023-05-18-we-love-openscapes). This folder name will become the slug of your post's URL (e.g. https:://openscapes.com/blog/2023-05-18-we-love-openscapes/)

2. Inside your new blog folder, add a file named index.qmd (it must be named index.qmd) -- this is where you'll write your blog post (e.g. /blog/2023-05-18-we-love-openscapes/index.qmd)

3. I recommend adding any images you plan to use in your blog post to this same folder (including the preview image that appears on the listing page) so that you can easily call them using relative file paths (e.g. to add the image /blog/2023-05-18-we-love-openscapes/other-image.png, to your blog post, the file path would be, other-image.png, since it is relative to the index.qmd file within the same folder). Note: this is not required, but a suggested convention moving forward. You will notice that ported blog posts (from the beginning of the blog through 2023-05-11) do not follow this convention (for speed/ease of porting, we specify relative file paths from each blog post to the /img/blog folder in the repository's root directory -- a relic of the {blogdown} organizational structure).

The _metadata.yml file

This file lives inside the /blog directory (i.e. /blog/_metadata.yml). Any metadata options specified in this file apply to all blog posts within the /blog directory.

Blog post YAML

Blog post-level metadata options are specified in the YAML metadata header of each index.qmd file. They all have this general structure (though you're not limited to these YAML options):

---
title: "blog post title"
description: "an optional short description" 
author: Author1, Author2, etc.
date: YYYY-MM-DD
categories:
  - community # list as many categories as you'd like
  - champions
  - noaa-fisheries
image: image.png # this image should live in the the blog post's directory (folder); otherwise, specify a relative file path
---

Categories

Unlike {blogdown}, which allowed for both categories and tags on individual blog posts, Quarto blogs only support categories. Any tags & categories from the old site were merged under the categories YAML option, as shown above. List as many as you'd like here.

Blog posts are tagged using the following categories (based off initial discussions with Julie, some decisions made on-the-fly by Sam, updated by Stef):

• art
• blog
• champions
• coding
• community-call
• conference
• how-we-work
• nasa-framework
• newsletter
• noaa-fisheries
• pathways
• quarto
• reflections
• water-boards