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:

  1. Solution found here: Download Hadley Wickham’s emo package and type `r emo::ji("smile")` into the text of the .Rmd file.

  2. 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”.

Here is the code that I used for my /archetype/template.md (modified from Leo Collado-Torres’ archetype):

---
title: "{{ replace .TranslationBaseName "-" " " | title }}"
date: "{{ .Date }}"
author: Sharleen Weatherley
summary: "This is the summary that will appear on the main page."
description: "This is the description that will appear on Twitter."
draft: false

tags:
- tag1
- tag2

twitterImg: http://res.publicdomainfiles.com/pdf_view/145/13978843819386.jpg
coverImage: http://res.publicdomainfiles.com/pdf_view/145/13978843819386.jpg
thumbnailImage: http://res.publicdomainfiles.com/pdf_view/145/13978843819386.jpg

coverCaption: "A short caption (Source: Source)"
thumbnailImagePosition: left
autoThumbnailImage: yes
coverSize: partial


---

```{r setup, echo = FALSE, warning = FALSE, message = FALSE}

knitr::opts_chunk$set(
  comment = "",
  warning = FALSE,
  echo = TRUE,
  message = FALSE
)

library(devtools) # for session_info()

```

<hr>

# Session info

```{r reproducibility, echo = FALSE}

devtools::session_info()

```

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.

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

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.0.2 (2020-06-22)
 os       Windows 10 x64              
 system   x86_64, mingw32             
 ui       RTerm                       
 language (EN)                        
 collate  English_Canada.1252         
 ctype    English_Canada.1252         
 tz       America/New_York            
 date     2020-09-04                  

- Packages -------------------------------------------------------------------
 ! package     * version    date       lib source                     
 P assertthat    0.2.1      2019-03-21 [?] CRAN (R 4.0.0)             
 P backports     1.1.8      2020-06-17 [?] CRAN (R 4.0.0)             
 P blogdown      0.20       2020-06-23 [?] CRAN (R 4.0.2)             
 P bookdown      0.20       2020-06-23 [?] CRAN (R 4.0.0)             
 P callr         3.4.3      2020-03-28 [?] CRAN (R 4.0.0)             
 P cli           2.0.2      2020-02-28 [?] CRAN (R 4.0.0)             
 P crayon        1.3.4      2017-09-16 [?] CRAN (R 4.0.0)             
 P desc          1.2.0      2018-05-01 [?] CRAN (R 4.0.0)             
 P devtools    * 2.3.1      2020-07-21 [?] CRAN (R 4.0.2)             
 P digest        0.6.25     2020-02-23 [?] CRAN (R 4.0.0)             
 P ellipsis      0.3.1      2020-05-15 [?] CRAN (R 4.0.2)             
 P emo         * 0.0.0.9000 2020-07-07 [?] Github (hadley/[email protected])
 P evaluate      0.14       2019-05-28 [?] CRAN (R 4.0.0)             
 P fansi         0.4.1      2020-01-08 [?] CRAN (R 4.0.0)             
 P fs            1.5.0      2020-07-31 [?] CRAN (R 4.0.2)             
 P generics      0.0.2      2018-11-29 [?] CRAN (R 4.0.0)             
 P glue          1.4.1      2020-05-13 [?] CRAN (R 4.0.2)             
 P here        * 0.1        2017-05-28 [?] CRAN (R 4.0.2)             
 P htmltools     0.5.0      2020-06-16 [?] CRAN (R 4.0.2)             
 P knitr         1.29       2020-06-23 [?] CRAN (R 4.0.2)             
 P lubridate     1.7.9      2020-06-08 [?] CRAN (R 4.0.2)             
 P magrittr      1.5        2014-11-22 [?] CRAN (R 4.0.0)             
 P memoise       1.1.0      2017-04-21 [?] CRAN (R 4.0.0)             
 P pkgbuild      1.1.0      2020-07-13 [?] CRAN (R 4.0.2)             
 P pkgload       1.1.0      2020-05-29 [?] CRAN (R 4.0.2)             
 P prettyunits   1.1.1      2020-01-24 [?] CRAN (R 4.0.0)             
 P processx      3.4.3      2020-07-05 [?] CRAN (R 4.0.2)             
 P ps            1.3.4      2020-08-11 [?] CRAN (R 4.0.2)             
 P purrr         0.3.4      2020-04-17 [?] CRAN (R 4.0.0)             
 P R6            2.4.1      2019-11-12 [?] CRAN (R 4.0.0)             
 P Rcpp          1.0.5      2020-07-06 [?] CRAN (R 4.0.2)             
 P remotes       2.2.0      2020-07-21 [?] CRAN (R 4.0.2)             
   renv          0.11.0     2020-06-26 [1] CRAN (R 4.0.2)             
 P rlang         0.4.7      2020-07-09 [?] CRAN (R 4.0.2)             
 P rmarkdown     2.3        2020-06-18 [?] CRAN (R 4.0.2)             
 P rprojroot     1.3-2      2018-01-03 [?] CRAN (R 4.0.0)             
 P sessioninfo   1.1.1      2018-11-05 [?] CRAN (R 4.0.0)             
 P stringi       1.4.6      2020-02-17 [?] CRAN (R 4.0.0)             
 P stringr       1.4.0      2019-02-10 [?] CRAN (R 4.0.0)             
 P testthat      2.3.2      2020-03-02 [?] CRAN (R 4.0.0)             
 P usethis     * 1.6.1      2020-04-29 [?] CRAN (R 4.0.2)             
 P withr         2.2.0      2020-04-20 [?] CRAN (R 4.0.0)             
 P xfun          0.16       2020-07-24 [?] CRAN (R 4.0.2)             
 P yaml          2.2.1      2020-02-01 [?] CRAN (R 4.0.0)             

[1] C:/Users/shw/Desktop/blog2/renv/library/R-4.0/x86_64-w64-mingw32
[2] C:/Users/shw/AppData/Local/Temp/RtmpmIaJJp/renv-system-library

 P -- Loaded and on-disk path mismatch.