作者：Yihui Xie
译者：郑宝童
日期：2021.05.24

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

你可以使用knitr中的块引擎来生成自定义块，例如，engine = 'block',或者更紧凑的语法’```{block}。这个引擎应该与chunk选项type一起使用，chunk选项类型接受一个字符串.当使用 block 引擎时，如果输出格式是HTML，它将生成一个<div> 来环绕块内容，如果输出格式是LaTeX，则生成一个LaTeX环境。type 选项指定 <div> 的类型和LaTeX环境的名称。例如，此块的HTML输出

  1. ```{block, type='FOO'}
  2. Some text for this block.
  1. will be this:

Some text for this block. 

  1. and the LaTeX output will be this:

\begin{FOO} Some text for this block. \end{FOO}

  1. > 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`:
  3. 由作者决定如何定义代码块的样式。您可以在CSS中定义 `<div>`的样式，并通过YAML元数据中的`includes` 选项将其包含在输出中。类似地，您可以通过 `\newenvironment` 定义LaTeX环境，并通过`includes` 选项将其定义在LaTeX输出中。例如，我们可以将以下样式保存在CSS文件中，比如`style.css`:

div.FOO { font-weight: bold; color: red; }

  1. And the YAML metadata of the R Markdown document can be:

output: bookdown::html_book: includes:

  1.   in_header: style.css
  1. We have defined a few types of blocks for this book to show notes, tips, and warnings, etc. Below are some examples:<br />R is free software and comes with ABSOLUTELY NO WARRANTY. You are welcome to redistribute it under the terms of the GNU General Public License versions 2 or 3. For more information about these matters see [http://www.gnu.org/licenses/](http://www.gnu.org/licenses/).<br />R is free software and comes with ABSOLUTELY NO WARRANTY. You are welcome to redistribute it under the terms of the GNU General Public License versions 2 or 3. For more information about these matters see [http://www.gnu.org/licenses/](http://www.gnu.org/licenses/).<br />R is free software and comes with ABSOLUTELY NO WARRANTY. You are welcome to redistribute it under the terms of the GNU General Public License versions 2 or 3. For more information about these matters see [http://www.gnu.org/licenses/](http://www.gnu.org/licenses/).<br />R is free software and comes with ABSOLUTELY NO WARRANTY. You are welcome to redistribute it under the terms of the GNU General Public License versions 2 or 3. For more information about these matters see [http://www.gnu.org/licenses/](http://www.gnu.org/licenses/).<br />R is free software and comes with ABSOLUTELY NO WARRANTY. You are welcome to redistribute it under the terms of the GNU General Public License versions 2 or 3. For more information about these matters see [http://www.gnu.org/licenses/](http://www.gnu.org/licenses/).
  2. > 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.,
  4. **knitr** `block` 被设计用来显示简单的内容(通常是一段纯文本)。您可以使用简单的格式化语法，如将某些单词加粗或斜体，但更高级的语法，如引用和交叉引用，将不起作用。然而，有一个名为`block2` 的替代引擎支持任意的**Markdown**语法，例如:

```{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.

如果你在有很多自定义的单元块，block2 引擎也比 block 引擎快, 但它的实现是基于 a hack的，所以我们不能100%确定它在未来是否总是有效。我们在Pandoc v1.17.2还没看到问题.

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引擎还有一个警告:如果块中的最后一个元素不是一个普通的段落，您必须在末尾留一个空行，例如:

  1. ```{block2, type='FOO'}
  2. Some text for this block [@citation-key].
  3. - a list item
  4. - another item
  5. - end the list with a blank line

```

The theorem and proof environments in Section 2.2.2 are actually implemented through the block2 engine.

第 2.2.2 节中的定理和证明环境实际上是通过block2 引擎实现的。
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.
对于基于block or block2 引擎的所有自定义的块，有一个块参数选项echo ，你可以是要用echo = TRUE显示块，或者使用echo = FALSE来隐藏块。