Blogdown

1.1 Pro tip: Cascading

Hugo’s cascade configuration works in blogdown too. setting that key an _index file passes config down to all descendants. For example here is how I set the default post quality in this blog:

cascade:
  certainty: 0
  novelty: 0
  usefulness: 0
  polish: 0

NB there is a subtlety here: hugo will correctly propagate this information through the blog when it render the content to the site. However, it does not appear to be propagated at the markup handling stage, at least not for the blogdown config. So I cannot pass e.g. reference handling options to pandoc this way, but I can pass options to page templates this way.

1.2 Pro tip: Setting classes on plots is ugly

Want to set classes for r-generated plots? Try this:

knitr::knit_hooks$set(class = function(before, options, envir) {
  if(before){
    sprintf("<div class='%s'>", options$class)
  }else{
    "</div>"
  }
})

Then in the chunk, we can use the new hook thusly:

```{r example-plot, class="blue-outline"}
plot(1:10, pch=21, bg="blue")
```

🤮

1.3 Pro-tip: double code fences

Wondering how I got the previous line of code to print? It was not quite obvious. See the double code fences trick. tl;dr uses the code type {verbatim}.

1.4 Pro-tip: comments

We can comment-out sections of document by making them into fenced code blocks with type {comment}. That is also included in the double code fences trick.

In hugo templates it is different; {/* a comment */} is the syntax.

1.5 Pro tip: Archetypes

Firstly, hugo archetypes automate some menial work if you have many posts of similar type (e.g. meeting minutes).

• Alison Hill: Archetypes
• L. Collado-Torres explains blogdown archetypes from the perspective of someone who worked it out the hard way

1.6 Pro tip: postprocessing

Maëlle Salmon writes about how to create smart code and figures using postprocessing hooks.

1.7 Pro tip: VS Code config

Hide extraneous crap using the following configuration:

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

1.8 Pro tip: cleaning up

Beware! blogdown will silently fail to render updates if there are lockfiles hanging around. It is easy to accumulate lockfiles if rendering crashes, which does happen from time to time. For me this seems to arise in pandoc errors, e.g. if there are errors in the bibliography/citation workflow. As long as no other rendering job is currently running, the fix is this:

find content -name "*.lock~" -delete

1.9 Outside RStudio

Many blogdown intros assume you are an RStudio user. RStudio is …fine. It does not incite enthusiasm in me, but it gets the job done.

If you are using VS code, Tianyi Shi’s excellent RMarkdown extension is useful; it allows you to compile the document from inside VSCode and other useful things.

Some of the design choices are explained well in blogdown: Knit on Save, or Save on Knit?.

From the command-line I find it best to build incrementally:

#!/usr/bin/env Rscript
library(blogdown)
options(blogdown.files_filter = blogdown::timestamp_filter)
blogdown::build_site(build_rmd = TRUE)

In version 1.0+ this becomes:

#!/usr/bin/env Rscript
library(blogdown)
blogdown::build_site(build_rmd = "timestamp")

In vs code Tianyi Shi’s excellent RMarkdown all-in-one extension is useful. An in-app browser preview can be useful.

As for running the server, this works:

#!/usr/bin/env Rscript
library(blogdown)
blogdown::build_site(build_rmd = "timestamp")
blogdown::serve_site()

On one hand it does not seem to automatically pick up changes to .Rmd files and thus save me a build step.

Alternatively I can manually run system hugo to serve the blogdown output eils

hugo serve --buildDrafts --poll 3000&

The --poll argument waits 3 seconds for my R build-script to finish before doing anything and thus is counterintuitively faster than an instant rebuild (which in practice is 10 different hugo rebuilds or something, each of which cases my browser to refresh and takes more than 3 seconds).

The blogdown-native methods runs hugo behind the scenes, but ensures it is the correct version etc.

Either way I need to trigger .Rmd compilation manually. Maybe that part works better from inside RStudio.

Since I am already off the blogdown piste at this point maybe I should be running the netlify dev server.

netlify dev --live

It has many features including draft deployments and ssh tunnel configuration for private preview.

1.10 Alternative markdown parsing settings

If I need alternate pandoc markdown settings… Finding the documentation of the exact configuration of the markdown parser is tricky 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+pipe_tables
  md_extensions: +citations+tex_math_single_backslash+backtick_code_blocks+emoji+footnotes+inline_notes-smart+pipe_tables

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.

2.1 Pro-tip: Header stuff

How to include Google Analytics in an RMarkdown generated GitHub Page?:

output:
  html_document:
    includes:
       in_header: header.html

Also works for favicons.

2.2 Pro-tip: better theorem syntax

The New theorem syntax is IMO nicer than the previous code-block thing, which IIRC is the one mentioned in the manual:

::: {.theorem #pyth name="Pythagorean theorem"}
For **a right triangle**, if $c$ denotes the length of the hypotenuse
and $a$ and $b$ denote the lengths of the other two sides, we have
$$a^2 + b^2 = c^2$$
:::

2.3 Pro-tip: Equation references

If I follow the UX hints I end up using the wrong syntax for aligned referenced equations. the canonical method is, in fact, to use a naked align environment, like so:

Ordinary text before naked LaTeX.

\begin{align}
  f\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k}
  (\#eq:binom)
\end{align}

An equation reference is \@ref(eq:binom)

This seems like it will not work during the writing because RStudio equation preview is broken for naked mathematical block environments, but in fact other candidate options (e.g. wrapping the {align} environment in $$ will work in preview but produce no output, or broken output, in the various backends.

5.1 Pro-tip: hugodown outside RStudio

What is not obvious 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.

5.2 Pro-tip: CSL is not configurable

CSL configuration is not quite done.

5.3 Pro-tip: Shortcodes broken

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