# 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 classic

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 shortcomings 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 option. You can also use some alternative options such as jekyll, although I do not know what benefit that would bring, and it would certainly lead you down an overgrown path.

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 (which uses pandoc internally) 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.

UPDATE: Alison Hill points out that blogdown in 2021 supports some more pure-markdown style workflows via the .RMarkdown format which augments the .Rmd format with an alternative processing of R Markdown so that … you know what? Just go and read her post. It is very clear and has more animations than I.

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.

Maëlle Salmon writes about how to create smart code and figures using postprocessing hooks. Also What to know before you adopt Hugo/blogdown.

pro tip for non-rstudio use build incrementally:

options(blogdown.files_filter = blogdown::timestamp_filter)
blogdown::build_site(build_rmd = TRUE)

In version 1.0+ this becomes:

blogdown::build_site(build_rmd = "timestamp")

## 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
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

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

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. If I understand rightly, 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?)