3 R Markdown

3.1 Tips

  • add library(magrittr) in the beginning, since I modify the .Rprofile while others may not

  • format float

rnorm(8) %>% formatC(digits = 3, format = 'f')
#> [1] "-1.400" "0.255"  "-2.437" "-0.006" "0.622"  "1.148"  "-1.822" "-0.247"
  • wider output

有时候嫌内容太窄(尤其是 print tibble 和用 R 生成的表格),需要把文档调宽一点。


knitr::opts_knit$set(width = 100)
options(width = 100)
  • include .Rmd source

See the .Rmd of this chapter for how I produce the following:

`r Sys.Date()`

  • syntax highlight pandoc --list-highlight-languages pandoc --list-highlight-styles

3.2 advanced

  • for reproducible research, refer to thesis figures for a comprehensive example

  • head_include won’t work without other options (such as -s), since the default output format seems to be HTML fragment.

  • character in pdf (svglite) device

(At least for svglite) knitr first prints the plot to a pdf device and then redraws it using the chunk device. If you plot contains character, the pdf device will generate thousands of warnings even the final plot look well.

the solution lives here 10:

options(device = "cairo_pdf")
  • debug rmarkdown::render()
old_chunk_hook <- knitr::knit_hooks$get('chunk')
new_chunk_hook <- function(x, options) {
    old_chunk_hook(x, options)
knitr::knit_hooks$set(chunk = new_chunk_hook)
knitr::opts_chunk$set(mutable_var = Sys.time()) # disable cache

3.3 bookdown

  • style guide
    • `` for inline code, file name and menu command
    • bold to indicate special meaning 11
    • italic to emphasis important points
  • custom header number and filename
## An Introduction {#my-custom-id-used-for-html-filename}
## unnumbered chapter {-}
## another unnumbered chapter {.unnumbered}
### section is also okay {#demo-section -}
  • you should use - rather than _ for figure label, to make cross-reference work.

  • Internationalization

  • you may inset the following to the head of chapter .Rmd

    knit: "bookdown::preview_chapter"

3.4 blogdown

  • NOT write {{, add space in between (hugo would treat it as shortcode).

  • cross-reference

The simplest way is [text](/post/.../slug), if the url of result .html is fixed (see [permalinks] in config.toml),

Another option is to utilize relative position of input files (absolute postion is forbidden since ref would cause error). From Hugo’s view, the input file is .html produced by knitr. .Rmd is fixed. An important requirement is to create _index.md in the directory containing input files. The syntax is as follows 12:

[link text](`r blogdown::shortcode('relref', 'relative/path/to/filename.html')`)
  • test theme

Hugo 的 theme 都会自带 exampleSite,如果你想自己 build (比如修改 exampleSite 之后看看效果):

cd theme-name/exampleSite
hugo --themesDir ../../ -t theme-name
  • after you rename a .Rmd file, remember to clean the old .html file (especially when you move .Rmd, otherwise there would be two post with same title and slug)

  • 以前用 RStudio 时,想用浏览器而不是Viewer panel 预览。鼓捣半天 options() 之后,发现 RStudio 会逗逼地 check if the browser can open http://www.rstuio.com, so utils::assignInNamespace('get_browser', function() {getOption('browser')}, 'servr')

  • let post URL like .Rmd path

  post = "/:sections/:slug/"

refer to here for sections, the most important thing is to create _index.md in the directory containing .Rmd

3.5 Hugo shortcode

Basically, shortcode is calling {{% shortcodename parameters %}}:

  • with markdown: {{% myshortcode %}}Hello **World!**{{% /myshortcode %}}
  • without markdown: {{< myshortcode >}}<p>Hello <strong>World!</strong></p>{{< /myshortcode >}}

In the first form, the text in between are treated as markdown. Ironically, it’s rendered by Pandoc’s rules in blogdown. So we’d better use the second form.

htmltools::HTML() in .Rmd can escape text from Pandoc and appear in .html verbatim. This provides us a way to write Hugo shortcode. I explored for a while and conclude the following ways:

  1. `r htmltools::HTML('...')`
  2. `r blogdown::shortcode(...)

  1. I don’t like the idea of setting encoding.↩︎

  2. For example, in normal context, knitr is treated as a typo; but knitr means a R package↩︎

  3. Due to the existence of . in filename, you have to wrap filename by "", such as {{% ref "foo.html" %}}. But the --smart option of Pandoc would ruin "" (\" isn’t useful since it would be convertd to &quot;). So you can only use R code to produce the relref shortcode.↩︎