9.1 Lightweight Pretty HTML Documents

When designing the rmarkdown package, we wished it could produce output documents that look pleasant by default, especially for HTML documents. Pandoc does not really style the HTML documents when converting Markdown to HTML, but rmarkdown does. As we mentioned in Section 3.1.4, the themes of HTML documents are based on Bootswatch, which actually relies on the Bootstrap library (https://getbootstrap.com). Although these themes look pretty, the major disadvantage is that their file sizes are relatively large. The size of an HTML document created from an empty R Markdown document with the html_document format is about 600Kb, which is roughly the total size of all CSS, JavaScript, and font files in the default theme.

If you are concerned about the file size but still want a fancy theme, you may consider the prettydoc package (Qiu 2020), which has bundled a few pretty themes (yet small in size). This package provides an output format prettydoc::html_pretty. An empty R Markdown document with this format generates an HTML file of about 70Kb.

9.1.1 Usage

The usage of prettydoc::html_pretty is very similar to html_document, with two major differences:

  • The theme option takes different values. The currently supported themes are "cayman", "tactile", "architect", "leonids", and "hpstr". Figure 9.1 shows the appearance of the leonids theme. See https://github.com/yixuan/prettydoc for screenshots of more themes.

  • The highlight option takes null, "github", or "vignette".

Below is an example of the YAML metadata of an R Markdown document that uses the prettydoc::html_pretty output format:

---
title: "Your Document Title"
author: "Document Author"
date: "2018-04-16"
output:
  prettydoc::html_pretty:
    theme: leonids
    highlight: github
---
The leonids theme of the prettydoc package.

FIGURE 9.1: The leonids theme of the prettydoc package.

9.1.2 Package vignettes

The prettydoc::html_pretty can be particularly useful for R package vignettes. We have mentioned the html_vignette format in Section 3.8 that also aims at smaller file sizes, but that format is not as stylish. To apply the prettydoc::html_pretty format to a package vignette, you may use the YAML metadata below:

---
title: "Vignette Title"
author: "Vignette Author"
output: prettydoc::html_pretty
vignette: >
  %\VignetteIndexEntry{Vignette Title}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

Do not forget to change the vignette title, author, and the index entry. You should also add prettydoc to the Suggests field of your package DESCRIPTION file, and the two package names knitr, rmarkdown to the VignetteBuilder field.

References

Qiu, Yixuan. 2020. Prettydoc: Creating Pretty Documents from R Markdown. https://github.com/yixuan/prettydoc.