Markdown 输出

概述

Quarto 可视化编辑器使用 Pandoc 生成 Markdown。这意味着在某些情况下，您的 Markdown 会被重写以符合标准的 Pandoc 惯例。例如，Pandoc 在列表项目符号后插入 3 个空格，并自动转义可能用于 Markdown 语法的字符。

以下是 Pandoc 生成的 Markdown 可能与您自己的 Markdown 写作风格不同的惯例列表：

优先使用 *text* 而不是 _text_
反引号代码块写作 ``` {.md} 而不是 ```md
没有属性的反引号代码块渲染为 4 个空格缩进的代码块
水平规则写作贯穿整个文档宽度的破折号
普通链接写作 <https://yihui.org> 而不是 https://yihui.org
项目符号和编号列表在列表项内容前使用额外的空格
引用块中的每一行都包含引用字符 (>)
表格标题写在表格下方而不是上方
多行 HTML 和 TeX 块使用显式原始属性（例如 ```{=tex}）
内联脚注被替换为段落正下方的脚注
嵌套的 div 在所有层次上使用 :::，只要它们的属性是不同的
未编号的部分用 {.unnumbered} 而不是 {-} 表示
用于 Markdown 语法的字符（例如 *、_ 或 #）总是被转义

虽然其中一些行为一开始可能会令人烦恼，但如果您决定可视化编辑模式对您的工作流程有用，那么最好只是适应 Pandoc 生成 Markdown 的方式来编写您自己的 Markdown。请注意，您还可以配置源代码模式使用这些惯例编写 Markdown，确保无论哪种模式进行编辑，都会生成相同的 Markdown。

编写选项

可以通过全局、项目或文件级别的选项自定义 Markdown 输出的某些方面，包括：

如何换行/断行（固定列、逐句换行等）。
脚注的写入位置（当前段落或节下方，或文档末尾）。
在从源代码模式保存 Markdown 时是否使用可视化模式的 Markdown 编写器（以确保从任一模式保存的文档之间的一致性）。

您可以在 R Markdown 全局选项或项目选项中设置这些选项，或者也可以使用 YAML 在每个文件的基础上设置这些选项（如下所述）。

换行

默认情况下，可视化编辑器编写的 Markdown 没有换行（段落全部占据一行）。这符合 RStudio 中 Markdown 源代码编辑模式的行为。

然而，如果您希望在特定列（例如 72 或 80）插入换行，或者在每句话后插入换行，您可以设置全局或每个项目的编辑器选项来实现这一点。

您也可以通过 wrap 选项在每个文档的基础上设置此行为。例如，要在 72 个字符后换行，您可以使用：

---
editor:
  markdown:
    wrap: 72
---

要在每句话后插入换行，使用 wrap: sentence。例如：

---
editor:
  markdown:
    wrap: sentence
---

用于句子换行的算法将很好地处理英语和日语文本，但对于其他语言可能无法准确检测句子的结尾。

如果您启用了全局换行选项并且想要为某个文档关闭换行，请使用 wrap: none。

参考文献

默认情况下，参考文献被写在相应脚注出现的块的末尾。您可以使用 references 选项覆盖此行为。

例如，要将参考文献写在节的末尾而不是块的末尾，您可以使用：

---
title: "我的文档"
editor:
  markdown:
    references: 
      location: block
---

references 选项的有效值为 block、section 和 document。

请注意，您还可以设置全局或每个项目的编辑器选项来控制参考文献的写入行为。

如果您正在将一组 Markdown 文档聚合成一个更大的作品，您可能希望确保所有文档中的参考文献标识符是唯一的（例如，您不希望 [^1] 出现多次）。您可以通过 prefix 选项确保唯一性。例如：

---
title: "我的文档"
editor:
  markdown:
    references: 
      location: block
      prefix: "mydoc"
---

这将导致此文档中的脚注使用指定的前缀（例如 [^mydoc-1]），确保它们在整个手稿中是全局唯一的。

请注意，如果你在Quarto 书籍项目中，则会自动应用引用 prefix，因此无需对 editor: markdown 进行任何更改。

规范模式

如果你有一个涉及在可视模式和源代码模式下编辑的工作流程，你可能希望无论哪种模式进行编辑，都能生成相同的markdown。你可以通过使用 canonical 选项来实现这一点。例如：

---
title: "我的文档"
editor:
  markdown:
    wrap: 72
    references: 
      location: block
    canonical: true
---

使用 canonical: true，可视模式和源代码模式的编辑将产生相同的markdown输出。这对于使用版本控制进行协作并且作者之间混合使用源代码和可视模式编辑的多作者情况特别有用。

已知限制

有一些Pandoc markdown扩展当前在可视编辑中不受支持。这些扩展很少使用，因此它们很可能不会影响你编辑的文档，但仍然值得注意。

扩展名	示例	行为
行内脚注	^[inline]	转换为数字脚注。
脚注标识符	[^longnote]	转换为数字脚注。
示例列表	(@) 第一个示例	读取/写入为普通编号列表。
自动列表编号	#. 第一个项目	读取/写入为普通编号列表。
参考链接	这是一个 [链接]	转换为普通链接。
MultiMarkdown属性	# 标题 [id]	转换为Pandoc属性。

可视编辑器无法解析非YAML标题块（例如旧式的 % 标题或MultiMarkdown标题），也无法解析非顶层的YAML元数据块。如果遇到这些形式的元数据，可视模式将无法加载并发出警告。