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 2021), 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
themeoption takes different values. The currently supported themes are"cayman","tactile","architect","leonids", and"hpstr". Figure 9.1 shows the appearance of theleonidstheme. See https://github.com/yixuan/prettydoc for screenshots of more themes.The
highlightoption takesnull,"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
---
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.