9.6 Custom blocks (*)

Section 2.7 of the bookdown book mentioned how we can use custom blocks in R Markdown to customize the appearance of blocks of content. This can be a useful way to make some content stand out from your report or book, to make sure that your readers take away the key points from your work. Examples of how these blocks could be used include:

  • display a warning message to make sure users are using up-to-date packages before running your analysis;

  • add a link at the beginning of your document to your GitHub repository containing the source;

  • highlight key results and findings from your analysis.

In this section, we will explain how to create your own custom blocks for both PDF and HTML output. They can both use the same formatting syntax in the R Markdown document, but require different configurations.

9.6.1 Syntax

The syntax for custom blocks is based on Pandoc’s fenced Div blocks. Div blocks are very powerful, but there is a problem at the moment: they mainly work for HTML output and do not work for LaTeX output.

Since version 1.16 of the rmarkdown package, it has been possible to convert Div blocks to both HTML and LaTeX. For HTML output, all attributes of the block will become attributes of the <div> tag. For example, a Div can have an ID (after #), one or multiple classes (class names are written after .), and other attributes. The following Div block

  1. ::: {#hello .greeting .message width="40%"}
  2. Hello **world**!
  3. :::

will be converted to the HTML code below:

  1. <div id="hello" class="greeting message" width="40%">
  2.   Hello <strong>world</strong>!
  3. </div>

For LaTeX output, the first class name will be used as the LaTeX environment name. You should also provide an attribute named data-latex in the Div block, which will be the arguments of the environment. This attribute can be an empty string if the environment does not need arguments. We show two simple examples below. The first example uses the verbatim environment in LaTeX, which does not have any arguments:

  1. ::: {.verbatim data-latex=""}
  2. We show some _verbatim_ text here.
  3. :::

Its LaTeX output will be:

  1. \begin{verbatim}
  2. We show some \emph{verbatim} text here.
  3. \end{verbatim}

When the block is converted to HTML, the HTML code will be:

  1. <div class="verbatim">
  2. We show some <em>verbatim</em> text here.
  3. </div>

The second example uses the center and minipage environments to display some text in a centered box of half of the page width.

  1. :::: {.center data-latex=""}
  3. ::: {.minipage data-latex="{.5\linewidth}"}
  4. This paragraph will be centered on the page, and
  5. its width is 50% of the width of its parent element.
  6. :::
  8. ::::

Note that we nested the minipage block in the center block. You need more colons for a parent block to include a child block. In the above example, we used four colons (you can use five or more) for the center block. The two blocks will be converted to the LaTeX code below:

  1. \begin{center}
  2. \begin{minipage}{.5\linewidth}
  3. This paragraph will be centered on the page, and
  4. its width is 50\% of the width of its parent element.
  5. \end{minipage}
  6. \end{center}

It is up to the user to define the appearance of their <div> blocks via CSS for the HTML output. Similarly, for LaTeX output, you may use the command \newenvironment to define the environment if it has not been defined, or \renewenvironment to redefine an existing environment in LaTeX. In the LaTeX definitions, you can decide on the appearance of these blocks in PDF. These customizations will normally be contained in their own files such as style.css or preamble.tex, and then included within the YAML options:

  1. ---
  2. output:
  3.   html_document:
  4.     css: style.css
  5.   pdf_document:
  6.     includes:
  7.       in_header: preamble.tex
  8. ---

Next we will demonstrate a few more advanced custom blocks that use custom CSS rules and LaTeX environments. You may find an additional example in Section 5.8, in which we arranged multiple blocks in a multi-column layout.

9.6.2 Adding a shaded box

First, we show how to include content in a shaded box. The box has a black background with an orange frame with rounded corners. The text in the box is in white.

For HTML output, we define these rules in a CSS file. If you are unfamiliar with CSS, there are plenty of free online tutorials, e.g., https://www.w3schools.com/css/.

  1. .blackbox {
  2.   padding: 1em;
  3.   background: black;
  4.   color: white;
  5.   border: 2px solid orange;
  6.   border-radius: 10px;
  7. }
  8. .center {
  9.   text-align: center;
  10. }

For LaTeX output, we create a new environment named blackbox and based on the LaTeX package framed, with a black background and white text:

  1. \usepackage{color}
  2. \usepackage{framed}
  3. \setlength{\fboxsep}{.8em}
  5. \newenvironment{blackbox}{
  6.   \definecolor{shadecolor}{rgb}{0, 0, 0}  % black
  7.   \color{white}
  8.   \begin{shaded}}
  9.  {\end{shaded}}

We used the framed package in this book because it is fairly lightweight, but it is not possible to draw a colored frame with rounded corners with this package. To achieve the latter, you will need more sophisticated LaTeX packages such as tcolorbox (https://ctan.org/pkg/tcolorbox), which offers a set of very flexible options for creating shaded boxes. You can find many examples in its documentation. The LaTeX environment below will create a shaded box of similar appearance to the above CSS example:

  1. \usepackage{tcolorbox}
  3. \newtcolorbox{blackbox}{
  4.   colback=black,
  5.   colframe=orange,
  6.   coltext=white,
  7.   boxsep=5pt,
  8.   arc=4pt}

Now we can use our custom box in both PDF and HTML output formats. The source code of the box is:

  1. :::: {.blackbox data-latex=""}
  2. ::: {.center data-latex=""}
  3. **NOTICE!**
  4. :::
  6. Thank you for noticing this **new notice**! Your noticing it has
  7. been noted, and _will be reported to the authorities_!
  8. ::::

The output is:

NOTICE!

Thank you for noticing this new notice! Your noticing it has been noted, and will be reported to the authorities!

9.6.3 Including icons

We can make custom blocks even more visually appealing by including images in them. Images can also be an effective way to convey the content of the block. For the following example, we assume that we are working within a directory structure below, which is a simplified version of what is used to build this book:

  1. directory/
  2. ├── your-report.Rmd
  3. ├── style.css
  4. ├── preamble.tex
  5. └── images/ 
  6.       └── ├── important.png
  7.           ├── note.png
  8.           └── caution.png

We show the source code and output of the example before we explain how everything works:

  1. ::: {.infobox .caution data-latex="{caution}"}
  2. **NOTICE!**
  4. Thank you for noticing this **new notice**! Your noticing it has
  5. been noted, and _will be reported to the authorities_!
  6. :::

The output is:

NOTICE!

Thank you for noticing this new notice! Your noticing it has been noted, and will be reported to the authorities!

For the HTML output, we can add an image to the box through the background-image property in CSS. We insert the image into the background, and add enough padding on the left-hand side to avoid the text overlapping with this image. If you are using local images, the file path to the images is provided relative to the CSS file. For example:

  1. .infobox {
  2.   padding: 1em 1em 1em 4em;
  3.   margin-bottom: 10px;
  4.   border: 2px solid orange;
  5.   border-radius: 10px;
  6.   background: #f5f5f5 5px center/3em no-repeat;
  7. }
  9. .caution {
  10.   background-image: url("images/caution.png");
  11. }

Note that we used two class names, .infobox and .caution, on the outer block. The infobox class will be used to define the shaded box with a colored border, and the caution class will be used to include the image. The advantage of using two classes is that we can define more blocks with different icons without repeating the setup of the shaded box. For example, if we need a warning box, we only need to define the following CSS rule without repeating rules in .infobox:

  1. .warning {
  2.   background-image: url("images/warning.png");
  3. }

Then you can create a warning box with the Markdown source code below:

  1. :::: {.infobox .warning data-latex="warning"}
  3. Include the actual content here.
  5. ::::

For the PDF output, we can create an infobox environment based on the blackbox environment defined in the previous example, and add the icon to the left side of the box. There are multiple ways of including images in a LaTeX environment. Here is only one of them (it does not precisely reproduce the box style defined in the CSS above):

  1. \newenvironment{infobox}[1]
  2.   {
  3.   \begin{itemize}
  4.   \renewcommand{\labelitemi}{
  5.     \raisebox{-.7\height}[0pt][0pt]{
  6.       {\setkeys{Gin}{width=3em,keepaspectratio}
  7.         \includegraphics{images/#1}}
  8.     }
  9.   }
  10.   \setlength{\fboxsep}{1em}
  11.   \begin{blackbox}
  12.   \item
  13.   }
  14.   {
  15.   \end{blackbox}
  16.   \end{itemize}
  17.   }

Below we show more example blocks with different icons:

NOTICE!

Thank you for noticing this new notice! Your noticing it has been noted, and will be reported to the authorities!

NOTICE!

Thank you for noticing this new notice! Your noticing it has been noted, and will be reported to the authorities!

NOTICE!

Thank you for noticing this new notice! Your noticing it has been noted, and will be reported to the authorities!

NOTICE!

Thank you for noticing this new notice! Your noticing it has been noted, and will be reported to the authorities!

Alternatively, you may use the LaTeX package awesomebox to generate boxes with icons in the PDF output. This package gives you a much larger number of icons to choose from. We give a brief example below: please refer to the package documentation for the possible LaTeX environments and their arguments.

  1. ---
  2. title: Awesome Boxes
  3. output:
  4.   pdf_document:
  5.     extra_dependencies: awesomebox
  6. ---
  8. A note box:
  10. ::: {.noteblock data-latex=""}
  11. Thank you for noticing this **new notice**! Your noticing it has
  12. been noted, and _will be reported to the authorities_!
  13. :::
  15. We define an R function `box_args()` to generate the arguments
  16. for the box:
  18. ```{r}
  19. box_args <- function(
  20.   vrulecolor = 'white',
  21.   hrule = c('\\abLongLine', '\\abShortLine', ''),
  22.   title = '', vrulewidth = '0pt',
  23.   icon = 'Bomb', iconcolor = 'black'
  24. ) {
  25.   hrule <- match.arg(hrule)
  26.   sprintf(
  27.     '[%s][%s][\\textbf{%s}]{%s}{\\fa%s}{%s}',
  28.     vrulecolor, hrule, title, vrulewidth, icon, iconcolor
  29.   )
  30. }
  31. ```
  33. Pass some arguments to the `awesomeblock` environment through
  34. an inline R expression:
  36. ::: {.awesomeblock data-latex="`r box_args(title = 'NOTICE!')`"}
  37. Thank you for noticing this **new notice**!
  39. Your noticing it has been noted, and _will be reported to
  40. the authorities_!
  41. :::