Update (2023): My blog has broken a couple times since writing this post about Blogdown, Hugo, and Netlify, and so I’ve redone my blog again, this time in Quarto and using Github Pages! I highly recommend using Quarto and Github Pages now. However, I have left the below post in case it helps anyone.

Background

In early 2019, I created a blogdown blog with the help of Alison Hill’s great article Up & Running with blogdown.

Recently, when I went to make a new blog post, I realized the blog was going to break since I’d updated some packages.

I decided I could either try to fix the blog, or make a new one (with a new theme!) and copy over my old blog posts. I chose the second option.

I learned a lot by doing this, so I’ve jotted down some things, in the hopes it might help myself or someone else!

So, in no particular order, here are some things I’ve learned! (Please let me know if anything is incorrect, I am by no means a blogdown expert.)

Read the freakin’ manual

Hugo Tranquilpeak has a great user documentation section.
blogdown itself has a book that has everything you could ever need to know about blogdown.
Alison Hill has a fantastic series of posts on her blog called “A Spoonful of Hugo” (with at least these four articles):
Including search terms like “blogdown rmd” or “hugo tranquilpeak” with my question gets different types of answers, some that will be more geared towards R and some that will be more geared towards hugo. I have found both types of searches to be helpful.

How can I get emojis to work❓

There are two options:

Solution found here: Download Hadley Wickham’s emo package and type `r emo::ji("smile")` into the text of the .Rmd file.
Another solution is to set enableEmoji = true in the config.toml.

Use `devtools::session_info()` at the bottom of every post

When transferring over my posts, two of them no longer worked due to external package updates!

So, following the great example set by David Neuzerling’s blog (and others), I will be adding devtools::session_info() to the bottom of my posts. I mean, it won’t fix the fact that my code no longer works, but it adds an extra layer of proof that it did, in fact, work, at that particular time, given that particular set of tools!

Use `renv`

I will be using renv with this blog, so that external package updates will no longer break my blog! (Hopefully.)

Making a template

I’ve added an archetype to my blog, following Alison Hill’s post on Archetypes (which references this blog post by Leo Collado-Torres).

An “archetype” is another word for template.

I created an archetype folder in my top-level directory, and added my template (called template.md) to that folder. This template archetype now pops up as an option when I use the RStudio Addin “New Post”.

To see the code that I used for my /archetype/template.md (modified from Leo Collado-Torres’ archetype), click here.

What to touch and what not to touch

The actual blog content goes in the /content folder, with posts going in the /content/posts/ folder and any other type of content going in its own section (like /content/about/ for the About section.)
Use page bundles to keep the content of the /content folder organized, and follow Yihui’s advice to change the format of the permalinks in the config.toml to "/:year/:month/:day/:slug/" (Page Bundles).
The /public folder can be deleted before rebuilding your website. In fact, why not regularly restart R, delete the /public folder and then blogdown:::serve_site() to make everything start fresh! (Troubleshooting Your Build).
The /archetype folder needs to be top-level (I had to create this folder myself)
The _output.yml file also needs to be top-level.
If you have images or CSS you want to include, create the appropriate folders in the /static folder (/static/img or /static/css), as these will be copied into the /public folder once the site is built (blogdown book).
Don’t touch the /theme folder! You should be able to do everything you need to do in the other folders.

Adding an “About” page

The “About” page is not really a post, it’s more of a standalone document. With the Tranquilpeak theme, there is an archetype called a “page” that you can use when creating it. The folder structure I used to create my “About” page was /content/about/index.md.

There is a difference between `.Rmd` and `.Rmarkdown` (who knew?)

Tranquilpeak theme has a cute default syntax highlighting, but I couldn’t figure out how to get it to work reliably. Until I realized the following (blogdown book):

Files saved as .Rmarkdown get converted to .markdown first, before .html.
However, files saved as .Rmd go straight to .html.

The fancy syntax highlighting only works in .markdown files (which only happens if I save the files as .Rmarkdown and not .Rmd). Some of the other CSS only works for .markdown files too. (See my section below on adding CSS.)

The blogdown book prefers .Rmd (as it allows for citations, which I have), so that’s what I’m using. I figured out a comparable syntax highlighting in the next section.

Syntax highlighting

Thanks to the blogdown book, I found out I could create a _output.yml file in the root directory, and include a .Rmd-specific syntax highlighting template for all my files. My _output.yml file looks like:

blogdown::html_page:
  highlight: tango
  toc: yes

Garrick Aden-Buie’s blog has a nice gallery comparing the different syntax-highlighting options.

This _output.yml file can also be used to add defaults to each post. For example, I added a line to include a Table of Contents. However, this cannot be overwritten in each individual post, so it’s an all-or-nothing thing.

Relative links

On my original blog, I included all absolute links. Yikes! So now, thanks to Alison Hill’s Page Bundles post (that references the blogdown book), I now know how to make relative links. Basically, if I want to include relative posts, I look at what the structure of the /public folder is, and use that as my relative link. For example, if I wanted to refer to this post, I would use /2020/07/08/how-to-remake-a-blogdown-blog-from-scratch/ as the link.

My settings for the “New Post” Addin

Add a title. Author and Date should be filled in automatically
Subdirectory is “post”
Don’t include categories
Add some relevant tags
Use the template.md archetype
Keep the default slug
Delete the “en-us” under Language
Format is .Rmd, not .Rmarkdown

Adding a bit of CSS

This is a notice

Watch out!

Warning!

Way to go!

I wanted to be able to add the above alert bars to my posts so, using a combination of these two sources: Bootstrap alerts and Custom CSS with Rmd, I created a custom CSS file in /static/css/mystyle.css with the following code:

/* @import url('https://maxcdn.bootstrapcdn.com/bootswatch/3.3.7/cosmo/bootstrap.min.css'); may conflict with default theme*/
@import url('https://fonts.googleapis.com/icon?family=Material+Icons'); /*google icons*/
@import url('https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css'); /*font awesome icons*/

.alert {
padding: 15px;
margin-bottom: 20px;
border: 1px solid transparent;
border-radius: 4px;
}
.alert-success {
color: #3c763d;
background-color: #dff0d8;
border-color: #d6e9c6;
}
.alert-danger,
.alert-error {
  color: #b94a48;
  background-color: #f2dede;
  border-color: #eed3d7;
}
.alert-info {
  color: #3a87ad;
  background-color: #d9edf7;
  border-color: #bce8f1;
}
.alert-warning {
  background-color: #fffcbb;
  border-color: #ffed83;
}

And in my actual posts, I need to write the following html:

<div class="well alert alert-info text-center" role="alert">
  <span class="fa fa-info-circle"></span>&nbsp;&nbsp;This is a notice
</div>

<div class="well alert alert-danger text-center" role="alert">
  <span class="fa fa-minus-circle"></span>&nbsp;&nbsp;Watch out!
</div>

<div class="well alert alert-warning text-center" role="alert">
  <span class="fa fa-exclamation-triangle"></span>&nbsp;&nbsp;Warning!
</div>

<div class="well alert alert-success text-center" role="alert">
  <span class="fa fa-check-circle"></span>&nbsp;&nbsp;Way to go!
</div>

Thoughts for next time I want to update my blog

If I want to change my theme again, I think I could simply swap out the current theme in the /theme folder, update the config.toml and /archetype/template.md files, and be done? I may also have to update all of the .yamls of each article.

I think I will just use Tom Mock’s blog post and use distill if I ever want to update my blog again!

Session info

─ Session info ───────────────────────────────────────────────────────────────
 setting  value
 version  R version 4.3.0 (2023-04-21 ucrt)
 os       Windows 11 x64 (build 22000)
 system   x86_64, mingw32
 ui       RTerm
 language (EN)
 collate  English_Canada.utf8
 ctype    English_Canada.utf8
 tz       Pacific/Honolulu
 date     2023-09-21
 pandoc   3.1.1 @ C:/Program Files/RStudio/resources/app/bin/quarto/bin/tools/ (via rmarkdown)

─ Packages ───────────────────────────────────────────────────────────────────
 package     * version    date (UTC) lib source
 assertthat    0.2.1      2019-03-21 [1] CRAN (R 4.3.1)
 cachem        1.0.8      2023-05-01 [1] CRAN (R 4.3.0)
 callr         3.7.3      2022-11-02 [1] CRAN (R 4.3.0)
 cli           3.6.1      2023-03-23 [1] CRAN (R 4.3.0)
 crayon        1.5.2      2022-09-29 [1] CRAN (R 4.3.0)
 devtools    * 2.4.5      2022-10-11 [1] CRAN (R 4.3.1)
 digest        0.6.31     2022-12-11 [1] CRAN (R 4.3.0)
 ellipsis      0.3.2      2021-04-29 [1] CRAN (R 4.3.0)
 emo         * 0.0.0.9000 2023-07-22 [1] Github (hadley/emo@3f03b11)
 evaluate      0.20       2023-01-17 [1] CRAN (R 4.3.0)
 fastmap       1.1.1      2023-02-24 [1] CRAN (R 4.3.0)
 fs            1.6.2      2023-04-25 [1] CRAN (R 4.3.0)
 generics      0.1.3      2022-07-05 [1] CRAN (R 4.3.0)
 glue          1.6.2      2022-02-24 [1] CRAN (R 4.3.0)
 here        * 1.0.1      2020-12-13 [1] CRAN (R 4.3.0)
 htmltools     0.5.5      2023-03-23 [1] CRAN (R 4.3.0)
 htmlwidgets   1.6.2      2023-03-17 [1] CRAN (R 4.3.0)
 httpuv        1.6.11     2023-05-11 [1] CRAN (R 4.3.1)
 jsonlite      1.8.4      2022-12-06 [1] CRAN (R 4.3.0)
 knitr         1.42       2023-01-25 [1] CRAN (R 4.3.0)
 later         1.3.1      2023-05-02 [1] CRAN (R 4.3.0)
 lifecycle     1.0.3      2022-10-07 [1] CRAN (R 4.3.0)
 lubridate     1.9.2      2023-02-10 [1] CRAN (R 4.3.0)
 magrittr      2.0.3      2022-03-30 [1] CRAN (R 4.3.0)
 memoise       2.0.1      2021-11-26 [1] CRAN (R 4.3.0)
 mime          0.12       2021-09-28 [1] CRAN (R 4.3.0)
 miniUI        0.1.1.1    2018-05-18 [1] CRAN (R 4.3.0)
 pkgbuild      1.4.0      2022-11-27 [1] CRAN (R 4.3.0)
 pkgload       1.3.2      2022-11-16 [1] CRAN (R 4.3.0)
 prettyunits   1.1.1      2020-01-24 [1] CRAN (R 4.3.0)
 processx      3.8.1      2023-04-18 [1] CRAN (R 4.3.0)
 profvis       0.3.8      2023-05-02 [1] CRAN (R 4.3.0)
 promises      1.2.0.1    2021-02-11 [1] CRAN (R 4.3.0)
 ps            1.7.5      2023-04-18 [1] CRAN (R 4.3.0)
 purrr         1.0.1      2023-01-10 [1] CRAN (R 4.3.0)
 R6            2.5.1      2021-08-19 [1] CRAN (R 4.3.0)
 Rcpp          1.0.10     2023-01-22 [1] CRAN (R 4.3.0)
 remotes       2.4.2      2021-11-30 [1] CRAN (R 4.3.0)
 rlang         1.1.1      2023-04-28 [1] CRAN (R 4.3.0)
 rmarkdown     2.21       2023-03-26 [1] CRAN (R 4.3.0)
 rprojroot     2.0.3      2022-04-02 [1] CRAN (R 4.3.0)
 rstudioapi    0.15.0     2023-07-07 [1] CRAN (R 4.3.1)
 sessioninfo   1.2.2      2021-12-06 [1] CRAN (R 4.3.0)
 shiny         1.7.4      2022-12-15 [1] CRAN (R 4.3.0)
 stringi       1.7.12     2023-01-11 [1] CRAN (R 4.3.0)
 stringr       1.5.0      2022-12-02 [1] CRAN (R 4.3.0)
 timechange    0.2.0      2023-01-11 [1] CRAN (R 4.3.0)
 urlchecker    1.0.1      2021-11-30 [1] CRAN (R 4.3.0)
 usethis     * 2.2.2      2023-07-06 [1] CRAN (R 4.3.1)
 vctrs         0.6.2      2023-04-19 [1] CRAN (R 4.3.0)
 xfun          0.39       2023-04-20 [1] CRAN (R 4.3.0)
 xtable        1.8-4      2019-04-21 [1] CRAN (R 4.3.0)
 yaml          2.3.7      2023-01-23 [1] CRAN (R 4.3.0)

 [1] C:/Users/sharl/AppData/Local/R/win-library/4.3
 [2] C:/Program Files/R/R-4.3.0/library

──────────────────────────────────────────────────────────────────────────────