1. Quarto blog template

I assume someone has already written a version of usethis::create_project() for creating a Quarto blog. Regardless, I’ve written bd2q::create_template() to generate a folder with the minimal structure required, which makes my life easier for testing purposes.

bd2q::create_template(q_path = "~/new-quarto-blog")

## ✔ Created template Quarto blog at /Users/mattdray/new-quarto-blog

The skeleton content is opinionated and differs a bit to the one generated through RStudio’s ‘new project’ menu, for example, but the structure is the same:

blog
├── about.qmd
├── index.qmd
├── posts/
│   └── metadata.yml
├── styles.css
└── blog.rproj

Of course, now we need to pull in the posts from the old {blogdown} blog.

2. Transfer posts and resources

Typically in a {blogdown} blog, all R Markdown posts and their rendered HTML files are stored together in content/post/ in the form YYYY-MM-DD-post-name.Rmd and YYYY-MM-DD-post-name.html. Resources, like images, live separately in static/post/ with a folder per post in the form YYYY-MM-DD-post-name_files/.

Here’s a simplified folder structure that focuses on a single post and its resources:

blog/
├── content/
│   └── post/
│       ├── YYYY-MM-DD-post-name.Rmd
│       └── YYYY-MM-DD-post-name.html
└── static/
    └── post/
        └── YYYY-MM-DD-post-name_files/
            └── image.png

Quarto simplifies this structure. Each post gets its own folder in posts/, like YYYY-MM-DD-post-name, which contains the post as index.qmd and a folder of resources. This means the post and all its content are stored together in one containing folder.

blog/
└── posts/
    └── YYYY-MM-DD-post-name/
        ├── index.qmd
        └── resources/
            └── image.png

To do the conversion, bd2q::transfer_posts() copies posts from a {blogdown} blog structure to a Quarto blog structure, setting up the required folders and renaming each post to index.qmd.

transfer_posts(
  bd_path = "~/old-blogdown-blog",
  q_path = "~/new-quarto-blog"
)

## ✔ Created posts/ directory structure.
## ℹ Copying posts.
## ✔ Copied 148 posts to /Users/mattdray/new-quarto-blog.

Once that’s been run, bd2q::transfer_resources() can copy each post’s resources into an accompanying subfolder, which defaults to the name ‘resources’. You can choose which file types you want transfer with the exts_keep argument.

transfer_resources(
  bd_path = "~/old-blogdown-blog",
  q_path = "~/new-quarto-blog",
  resources_dir = "resources",
  exts_keep = c("gif", "jpg", "jpeg", "png", "svg", "wav"),
)

## ℹ Copying resources.
## ✔ Copied 455 resources to each post's resources/ folder in Users/mattdray/new-quarto-blog/posts.

Of course this doesn’t account for everything, like bits of JavaScript and CSS related to the use of htmlwidgets. I’m not really bothered about this, because these should be recreated when I re-render each post.

Note that you can use bd2q::create_and_transfer() if you want to run create_template(), transfer_posts() and transfer_resources() all at once. Regardless, once you’ve got the structure sorted, you can begin to adjust the posts if you need to.

3. Tweak post content

There’s content in the body of each post that I want to get rid of or make more Quarto-like. I made a few functions that iterate over all the index.qmd files and replace or remove certain content.

One obvious necessity is to rebuild the resource paths (to images, sound files, etc), which can be done specifically with bd2q::update_resource_paths(). It defaults to creating paths to each post’s ‘resources’ subfolder, as generated by bd2q::transfer_resources(). For example, you could use a regular expression to match rows you know will contain a resource path and have them updated for the new Quarto folder structure (I tend to insert images with HTML rather than Markdown, hence the <img> tag in the example below).

update_resource_paths(
  q_path = "~/new-quarto-blog",
  resources_dir = "resources",
  resource_rx = "<img src="
)

## ℹ Updating posts.
## ✔ 148 posts updated.  

I also added two replace/remove functions that are a little more generic.

The first is bd2q::remove_line(), which deletes a single line from each post based on a provided regular expression. When I was messing around with converting the blog to Quarto manually, I found that the presence of the ‘draft’ status in the YAML header would prevent the post from appearing on the homepage, even if was set to ‘no’. As a result, you can run something like this to find and remove the lines that start with ‘draft’:

bd2q::remove_line(
  q_path = "~/new-quarto-blog",
  detect_rx = "^draft:"
)

## ℹ Making corrections.
## ✔ Removed lines matching the regular expression '^draft:' from 128 out of 148 posts.

That’s fine for individual lines, but what if you have a sequence of consecutive lines that you want to find and remove, or replace with some other text?

That’s what bd2q::replace_lines() does. Provide a vector of strings that exactly match some consecutive lines in each post, then provide a vector of strings to replace them with (or NULL to simply remove them)⁶.

This addresses another specific problem I was having. I wanted to update my custom session-info blocks at the bottom of each post so that they instead appear as a Quarto ‘appendix’. That can be done like this:

old_lines <- c(
  "---",
  "<details><summary>Session info</summary>",
  "```{r eval=TRUE, sessioninfo, echo=FALSE}",
  "sessioninfo::session_info()",
  "```",
  "</details>"
)

new_lines <- c(
  "## Details {.appendix}",
  "<details><summary>Session info</summary>",
  "```{r}",
  "#' eval = TRUE,",
  "#' echo = FALSE",
  'cat("Date:", cat(format(Sys.time(), format = "%Y-%m-%d")), "\n\n"); sessionInfo()',
  "```"
)

bd2q::replace_lines(
  q_path = "~/new-quarto-blog",
  match_str = old_lines,
  replacement_str = new_lines
)

## ℹ Making corrections.
## ✔ Removed lines matching the provided string vector from 9 out of 148 posts.   

Haha, uhoh, I was expecting to have fixed more posts than that! Looks like I might have written my custom session-info block slightly differently in each post (maybe an extra space or empty line?), so I’ll have to run the bd2q::replace_lines() multiple times to make sure I can replace it in each post that it appears.