Creating Pretty Documents from R Markdown

The Architect Theme

Yixuan Qiu

2019-07-16

Have you ever tried to find a lightweight yet nice theme for the R Markdown documents, just like this page?

Themes for R Markdown

With the powerful rmarkdown package, we could easily create nice HTML document by adding some meta information in the header, for example

The html_document engine uses the Bootswatch theme library to support different styles of the document. This is a quick and easy way to tune the appearance of your document, yet with the price of a large file size (> 700KB) since the whole Bootstrap library needs to be packed in.

For package vignettes, we can use the html_vignette engine to generate a more lightweight HTML file that is meant to minimize the package size, but the output HTML is less stylish than the html_document ones.

So can we do BOTH, a lightweight yet nice-looking theme for R Markdown?

The prettydoc Engine

The answer is YES! (At least towards that direction)

The prettydoc package provides an alternative engine, html_pretty, to knit your R Markdown document into pretty HTML pages. Its usage is extremely easy: simply replace the rmarkdown::html_document or rmarkdown::html_vignette output engine by prettydoc::html_pretty in your R Markdown header, and use one of the built-in themes and syntax highlighters. For example

Options and Themes

The options for the html_pretty engine are mostly compatible with the default html_document (see the documentation) with a few exceptions:

  1. Currently the theme option can take the following values. More themes will be added in the future.
    • cayman: Modified from the Cayman theme.
    • tactile: Modified from the Tactile theme.
    • architect: Modified from the Architect theme.
    • leonids: Modified from the Leonids theme.
    • hpstr: Modified from the HPSTR theme.
  2. The highlight option takes value from github and vignette.
  3. A new math parameter to choose between mathjax and katex for rendering math expressions. The katex option supports offline display when there is no internet connection.
  4. Options code_folding, code_download and toc_float are not applicable.

Offline Math Expressions

By default, html_pretty uses MathJax to render math expressions, for example inline math expressions \(x^2 + y^2 = z^2\), and display formulas:

\[ f(x)=\frac{1}{\sqrt{2\pi}\sigma}e^{-\frac{(x-\mu)^2}{2\sigma^2}} \]

However, using MathJax requires an internet connection. If you need to create documents that can show math expressions offline, simply add one line math: katex to the document metadata:

This option will enable KaTeX for rendering the math expressions, and all resource files will be included in for offline viewing. The offline document will be ~800k larger.

Elements

We demonstrate some commonly used HTML elements here to show the apprearance of themes.

Headers

Level 4

Level 5

Tables

Df Sum Sq Mean Sq F value Pr(>F)
Block 5 343.3 68.66 4.447 0.01594 *
N 1 189.3 189.28 12.259 0.00437 **
P 1 8.4 8.40 0.544 0.47490
K 1 95.2 95.20 6.166 0.02880 *
N:P 1 21.3 21.28 1.378 0.26317
N:K 1 33.1 33.14 2.146 0.16865
P:K 1 0.5 0.48 0.031 0.86275
Residuals 12 185.3 15.44

Lists

There are three kinds of lies:

  1. Lies
  2. Damned lies
  3. Statistics
    • Frequentists
    • Bayesian

Supported highlighters in prettydoc:

  • github: Style similar to Github
  • vignette: Style used by rmarkdown::html_vignette

Markups

Bold, italic, don’t say this.