Blogdown

Plus other RMarkdown-derived scholarly blogging systems


Blogdown is the academic blogging system that I use. It is a system to construct a website using pages made from rmarkdown and similar literate programming tools to write a blog with embedded diagrams and code and such. In its default state it just works, and is highly recommended. However, after a while there are a few frictions that one can avoid by being fancy (e.g. hugodown) Both basic blogdown and excessively fancy options are expanded here.

Blogdown

Blogdown might be the most popular move now, especially if you want to access the mind-share of other academics, such as the rbind community. See also the blogdown-book. This is what I currently use for this site. I recommend it because although it is not free from shortcoming it also does most things right by default, including things that only academics care about. It is built upon, per default, hugo which is an elegant and popular blogging platform. It is a great default option.

One point of friction is that hugo is well integrated with its own internal markdown processor, goldmark and much of the documentation reflects that. However, blogdown bypasses goldmark, using instead rmarkdown to render workbooks direct to HTML+images. This leads to pluses (equation and citation support) and minuses (many hugo tricks, notably shortcode) do not work. This is a bit of a hack, but it installs easily and works straight away, and it has a lot of flexibility. One could possibly work around some frictions by rendering to markdown, or using hugodown, which is a variant of blogdown that does precisely that.

Pro tip for VS code. Hide extraneous crap using the following configuration:

  "files.watcherExclude": {
    "**/output/**": true
  },
  "files.exclude": {
    "content/**/*.html": true
  }

See the blogdown-book, or the various academic intros, e.g. by Emi Tanaka or Rob Hyndman.

Some themes have been tested against blogdown.

If you are using vs code, Tianyi Shi‘s excellent RMarkdown extension is useful; it allows you to compile the document from inside VSCode.

Finding the documentation of the exact configuration fo the markdown parser is trick from google for some reason, and in fact I have already lost the link.

For my reference, I found the following _output.yml configuration options useful:

blogdown::html_page:
  toc: true
  dev: "svg"
  smartypants: false
  variant: markdown+citations+tex_math_single_backslash+backtick_code_blocks+emoji+footnotes+inline_notes-smart
  md_extensions: +citations+tex_math_single_backslash+backtick_code_blocks+emoji+footnotes+inline_notes-smart

I am not sure which of variant and md_extensions is the configuration I need to pass my preferred options to pandoc. I should work that out one day.

hugodown

hugodown is a twist on blogdown.

Hugodown is an experimental package that aims to facilitate the use of RMarkdown and hugo together. It’s similar to blogdown, but is focussed purely on Hugo websites, and enforces a stricter partitioning of roles: hugodown is responsible for transforming .Rmd to .md, and hugo is responsible for transforming .md to .html. …it strives to provide the best of blogdown's two Rmarkdown variants: .Rmd and .Rmarkdown.

Feature hugodown .Rmd blogdown .Rmd blogdown .Rmarkdown
Output .md .html .markdown
Runs R code y y y
Table of contents y n y
Bibliography y y n
MathJax y y ?
HTML widgets y y n
Cross-references n y y
devtools::install_github("r-lib/hugodown")

The documentation is not great — I think this is mostly an internal theme for the Rstudio blog and in particular tidymodels. Source is here. Speed run is here.

The main win over blogdown is the consistent rendering across different posts, particular of the Table of Contents, and a less flakey preview server.

If something breaks, best steal the working tricks from the default theme from hugo-graphite.

What is not obvious here is the command to compile a page (the manual tells you to click a button, which presumes you are using RStudio, which I do not personally enjoy.) It seems to be

knitr::knit("PATH/TO/FILE", "hugodown::md_document")

but this compiles the output in the wrong place per default. TBC.

A recommended configuration of this is using Wowchemy extensions to hugo.

Pain points

CSL configuration is not quite done.

shortcode support is broken, which would have been a real win in terms of opening up brainshare from the hugo ecosystem.

distill + radix

Another project by the crew at RStudio, distill is an academic writing system that overlaps in features and toolkit with blogdown but is oriented towards journal article-style typography. It was extracted from the journal Distill. As befits such an origin story, it has lavish article and citation metadata support. Emi Tanaka’s comparison makes the points of difference clear. (tl;dr; It makes academic output easy and other webby stuff maybe harder?)