2.7 Custom blocks
You can generate custom blocks using the block engine in knitr, i.e., the chunk option engine = 'block', or the more compact syntax ```{block}. This engine should be used in conjunction with the chunk option type, which takes a character string. When the block engine is used, it generates a <div> to wrap the chunk content if the output format is HTML, and a LaTeX environment if the output is LaTeX. The type option specifies the class of the <div> and the name of the LaTeX environment. For example, the HTML output of this chunk
```{block, type='FOO'}
Some text for this block.
```will be this:
<div class="FOO">
Some text for this block.
</div>and the LaTeX output will be this:
\begin{FOO}
Some text for this block.
\end{FOO}It is up to the book author how to define the style of the block. You can define the style of the <div> in CSS and include it in the output via the includes option in the YAML metadata. Similarly, you may define the LaTeX environment via \newenvironment and include the definition in the LaTeX output via the includes option. For example, we may save the following style in a CSS file, say, style.css:
div.FOO {
font-weight: bold;
color: red;
}And the YAML metadata of the R Markdown document can be:
---
output:
bookdown::html_book:
includes:
in_header: style.css
---We have defined a few types of blocks for this book to show notes, tips, and warnings, etc. Below are some examples:
The knitr block engine was designed to display simple content (typically a paragraph of plain text). You can use simple formatting syntax such as making certain words bold or italic, but more advanced syntax such as citations and cross-references will not work. However, there is an alternative engine named block2 that supports arbitrary Markdown syntax, e.g.,
```{block2, type='FOO'}
Some text for this block [@citation-key].
- a list item
- another item
More text.
```The block2 engine should also be faster than the block engine if you have a lot of custom blocks in the document, but its implementation was based on a hack, so we are not 100% sure if it is always going to work in the future. We have not seen problems with Pandoc v1.17.2 yet.
One more caveat for the block2 engine: if the last element in the block is not an ordinary paragraph, you must leave a blank line at the end, e.g.,
```{block2, type='FOO'}
Some text for this block [@citation-key].
- a list item
- another item
- end the list with a blank line
```The theorem and proof environments in Section 2.2.2 are actually implemented through the block2 engine.
For all custom blocks based on the block or block2 engine, there is one chunk option echo that you can use to show (echo = TRUE) or hide (echo = FALSE) the blocks.