A note from the authors: Some of the information and instructions in this book are now out of date because of changes to Hugo and the blogdown package. If you have suggestions for improving this book, please file an issue in our GitHub repository. Thanks for your patience while we work to update the book, and please stay tuned for the revised version!
In the meantime, you can find an introduction to the changes and new features in the v1.0 release blog post and this "Up & running with blogdown in 2021" blog post.
— Yihui, Amber, & Alison
1.6 R Markdown vs. Markdown
如果您不熟悉 R Markdown，请参阅 Appendix A 的快速教程。当您创建新帖子时，您必须决定是否要使用 R Markdown 还是普通 Markdown，如 Figure 1.7 所示。
Table 1.3 总结了三种文件扩展名之间的主要区别。请注意，.Rmarkdown 始终呈现为 Markdown (.markdown)，但 .Rmd 可能呈现为 HTML 或 Markdown，具体取决于全局选项 blogdown.method = "html" 或 "markdown"。
| Feature | .Rmd | .Rmarkdown | .md/.markdown |
|---|---|---|---|
| Run R code | yes | yes | no |
| Bibliography | yes | yes | no |
| Cross references | yes | yes | no |
| LaTeX math | yes | maybe | maybe |
| HTML widgets | yes | yes | no |
基本上，您无法在普通 Markdown 文档（.md 或 .markdown）中执行任何 R 代码，而在 R Markdown 文档（.Rmd 或 .Rmarkdown）中，您可以嵌入 R 代码块（```{r}）。但是，您仍然可以使用受防护代码块 ```r 的语法将 R 代码嵌入到纯 Markdown 中（请注意，没有大括号 {}）。此类代码块将不会被执行，并且可能适合纯粹的演示目的。下面是 R Markdown 中 R 代码块的示例：
下面是纯 Markdown 格式的 R 代码块示例：
普通的 Markdown 帖子通过 Goldmark (用 Go 语言编写并被 Hugo 采用的 Markdown 渲染器) 直接渲染为 HTML。R Markdown 帖子首先通过 R 包 rmarkdown 和 bookdown 编译为 Markdown，这意味着您可以在 blogdown 中使用 bookdown’s Markdown extensions 扩展的大部分功能。然后，Markdown 帖子可以通过 Goldmark 或 Pandoc 呈现为 HTML。对于后一种情况，您还可以使用 Pandoc’s Markdown 中更丰富的功能（更多信息请参见 Section 1.6.2）。
1.6.1 Basic features of R Markdown
如果您将 R Markdown (Allaire et al. 2023) 与 blogdown 结合使用，我们建议您至少阅读一次 Pandoc 和 bookdown 的文档，以了解所有可能的功能。我们不会在本书中重复详细内容，而是在下面简要列出功能，这些功能也在示例网站 https://blogdown-demo.rbind.io 上进行了演示。
Inline formatting:
_italic_/**bold**text and`inline code`.Inline elements: subscripts (e.g.,
H~2~0) and superscripts (e.g.,R^2^); links ([text](url)) and images.Footnotes:
text[^1];[^1]: your footnote content. Note that the inline footnotetext^[footnote]is no longer supported by Hugo. As Hugo switched the default Markdown renderer to Goldmark since v0.60.0, which does not support inline footnotes.Block-level elements: paragraphs; numbered and unnumbered section headers; ordered and unordered lists; block quotations; fenced code blocks; tables; horizontal rules.
Math expressions and equations.
Theorems and proofs.
R code blocks that can be used to produce text output (including tables) and graphics. Note that equations, theorems, tables, and figures can be numbered and cross-referenced.
Citations and bibliography.
HTML widgets, and Shiny apps embedded via
<iframe>.
如果你不需要 Table 1.3 中的额外功能，你可以只写一个普通的 Markdown 帖子 (.md)，否则你需要使用 R Markdown。正如我们之前提到的，R Markdown 有两种可能的格式：一种文件扩展名为 .Rmd，另一种文件扩展名为 .Rmarkdown。后者总是渲染为 Markdown，由 Hugo 的 Markdown 渲染器（Goldmark）处理。前者可以呈现为 HTML 或 Markdown，我们将在下一节中解释。
1.6.2 Render R Markdown to Markdown or HTML?
如果您对帖子使用文件扩展名 .Rmd，则需要决定是将其呈现为 .html 还是 .md。本质上，这意味着您是否要使用 Pandoc 还是 Goldmark 来渲染帖子。要通过 Pandoc 渲染为 .html，您需要设置全局选项 options(blogdown.method = "html")。要渲染为 .md，您可以设置 options(blogdown.method = "markdown")。
总的来说，Pandoc 的 Markdown 功能比 Goldmark 更丰富。例如，Goldmark 不支持 LaTeX 数学，而 Pandoc 支持。我们已在 blogdown 中的默认主题 (hugo-lithium) 中添加了 MathJax 支持，以在 HTML 页面上呈现 LaTeX 数学，但对于纯 Markdown 帖子有一个警告：您必须在一对反引号 `$math$` 中包含内联数学表达式，例如 `$S_n = \sum_{i=1}^n X_i$`。同样，显示样式的数学表达式必须写成 `$$math$$`。对于要呈现为 .html 的 .Rmd 帖子，您可以使用 $math$ 作为内联数学表达式，使用 $$math$$ 作为显示样式表达式。9
将 .Rmd 渲染为 .html 的主要缺点是：
您可能会牺牲一些渲染网站的速度，但是由于 blogdown 中的缓存机制，这可能不会被注意到（更多内容请参见 Section D.3）。 Hugo 在处理纯 Markdown 文件时非常快，通常渲染几百个帖子需要不到一秒的时间。
您网站的源目录中将会有一些中间 HTML 文件，因为 blogdown 必须调用 rmarkdown 将
*.Rmd文件预渲染为*.html。如果您有 R 代码块中的绘图输出或启用了 knitr 的缓存，您还将拥有图形 (*_files/) 和缓存 (*_cache/) 的中间文件夹。除非你非常关心网站源代码存储库的“清洁度”（特别是当你使用像 GIT 这样的版本控制工具时），否则这些中间文件应该无关紧要。
将 .Rmd 渲染为 .md（或 .Rmarkdown 渲染为 .markdown）有两个主要限制：
您不能使用仅 Pandoc 支持的 Markdown 功能，例如受隔离的
Divs。仅当您应用 Section B.3 中提到的 JavaScript 解决方案时，数学表达式才有效。
将帖子渲染为 Markdown 而不是 HTML 的主要优点是输出文件更干净，因为它们是 Markdown 文件（相比之下，HTML 文件通常包含大量 HTML 标签，这些标签对于人类来说很难阅读）。您可以更轻松地阅读帖子的输出，而无需查看呈现的实际网页。这在查看 GitHub pull 请求时特别有用。请注意，还支持编号表、图形、方程和定理。您不能直接在表格或图形标题中使用 Markdown 语法，但可以使用文本引用作为解决方法（请参阅 bookdown 的文档）。
1.6.3 Customize the R Markdown output format
对于任何 R Markdown 文档（不特定于 blogdown），您必须指定输出格式。rmarkdown 包（例如 html_document 和 pdf_document）和其他扩展包（例如 tufte::tufte_html 和 bookdown::gitbook）中有许多可能的输出格式。当然，网站的输出格式应该是 HTML。我们在 blogdown 中提供了一个输出格式函数 blogdown::html_page，所有的 R Markdown 文件都是使用这种格式渲染的。它基于输出格式 bookdown::html_document2，这意味着除了 Pandoc 的功能之外，它还继承了 bookdown 的很多功能。例如，您可以对数学方程、图形、表格和定理等进行编号和交叉引用。有关语法的更多详细信息，请参阅 bookdown book (Xie 2016) 的 Chapter 2。
请注意，输出格式 bookdown::html_document2 又继承自 rmarkdown::html_document，因此您需要查看帮助页面 ?rmarkdown::html_document 以了解 blogdown::html_page 格式的所有可能选项。如果要更改此输出格式的选项的默认值，可以将输出字段添加到 YAML metadata 中。例如，我们可以向页面添加目录，将图形宽度设置为 6 英寸，并通过在 YAML 中设置以下选项来使用 svg 设备进行绘图：
---
title: "My Awesome Post"
author: "John Doe"
date: "2017-02-14"
output:
blogdown::html_page:
toc: true
fig_width: 6
dev: "svg"
---要全局设置 blogdown::html_page() 的选项（即，将某些选项应用于所有 Rmd 文件），您可以在网站的根目录下创建一个 _output.yml 文件。此 YAML 文件应直接包含输出格式（不要将输出格式放在 output 选项下），例如，
目前，blogdown 并不支持 rmarkdown::html_document 的所有功能，例如 df_print、code_folding、code_download 等。
如果您的代码块有图形输出，我们建议您避免在块标签中使用空格等特殊字符。理想情况下，您应该只使用字母数字字符和破折号，例如 ```{r, my-label} 而不是 ```{r, my label}。
不建议更改 R Markdown 中的 knitr chunk 选项 fig.path 或 cache.path。这些选项的默认值最适合 blogdown。如果您愿意，请阅读 Section D.5 以了解技术原因。
如果您正在编写 R Markdown 帖子，但不希望 blogdown 对其进行编译，您可以暂时将其文件扩展名从 .Rmd 更改为另一个未知扩展名，例如 .Rmkd。
References
纯 Markdown 文档需要反引号的原因是我们必须防止 LaTeX 代码被 Blackfriday 解释为 Markdown。反引号将确保内部内容不会被转换为 Markdown 到 HTML，例如，
`$$x *y* z$$`将被转换为<code>$$x *y* z$$</code>。如果没有反引号，它将被转换为$$x <em>y</em> z$$，这不是 MathJax 的有效 LaTeX 数学表达式。当数学表达式中包含其他特殊字符（例如下划线）时，可能会出现类似的问题。↩︎