Markdown 基础

概述

Quarto 基于 Pandoc，并使用其变体 Markdown 作为基础文档语法。Pandoc markdown 是 John Gruber 的 Markdown 语法的扩展和略微修订版。

Markdown 是一种纯文本格式，旨在方便书写，更重要的是方便阅读：

Markdown 格式的文档应该可以按原样发布，就像纯文本一样，而不会看起来像被标记了标签或格式说明。– John Gruber

本文档提供了最常用的 Markdown 语法示例。更深入的文档请参见 Pandoc’s Markdown 的完整文档。

字体

Markdown Syntax	Output
*italics*, **bold**, ***bold italics***	italics, bold, bold italics
superscript^2^ / subscript~2~	superscript2 / subscript2
~~strikethrough~~	strikethrough
`verbatim code`	verbatim code

标题

Markdown Syntax	Output
# Header 1	Header 1
## Header 2	Header 2
### Header 3	Header 3
#### Header 4	Header 4
##### Header 5	Header 5
###### Header 6	Header 6

图像链接

Markdown Syntax	Output
<https://quarto.org>	https://quarto.org
[Quarto](https://quarto.org)	Quarto
	Caption
[](https://quarto.org)
[](https://quarto.org "An elephant")
[{fig-alt="Alt text"}](https://quarto.org)

列表

Markdown Syntax	Output
* unordered list + sub-item 1 + sub-item 2 - sub-sub-item 1	unordered list sub-item 1 sub-item 2 sub-sub-item 1
* item 2 Continued (indent 4 spaces)	item 2 Continued (indent 4 spaces)
1. ordered list 2. item 2 i) sub-item 1 A. sub-sub-item 1	ordered list item 2 sub-item 1 sub-sub-item 1
(@) A list whose numbering continues after (@) an interruption	A list whose numbering continues after an interruption
::: {} 1. A list ::: ::: {} 1. Followed by another list :::	A list Followed by another list
term : definition	term definition

请注意，与其他 Markdown 呈现器（尤其是 Jupyter 和 GitHub）不同，Quarto 中的列表需要在列表上方留出一整行空白。否则，列表将无法以列表形式呈现，而只能以普通文本形式显示在一行中。

表格

Markdown 语法

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

效果

Right	Left	Default	Center
12	12	12	12
123	123	123	123
1	1	1	1

更多信息，请参阅 表格 一文。

代码

使用 ``` 来划分代码块：

```
code
```

添加语言语法，高亮显示代码块：

```python
1 + 1
```

Pandoc 支持超过 140 种不同语言 的语法高亮显示。如果不支持您的语言，您可以使用 “默认”语言来获得类似的可视化处理：

```default
code
```

如果要创建 HTML 输出，有多种代码块输出选项可供选择。更多详情，请参阅 [HTML 代码] 一文（…/output-formats/html-code.qmd）。

数学公式

内联数学使用 $ 分隔符，显示数学使用 $$ 分隔符。例如

Markdown Syntax	Output
inline math: $E = mc^{2}$	inline math: \(E=mc^{2}\)
display math: $$E = mc^{2}$$	display math: \[E = mc^{2}\]

如果要定义自定义 TeX 宏，请将其包含在.hidden块中的$$分隔符内。例如：

::: {.hidden}
$$
 \def\RR{{\bf R}}
 \def\bold#1{{\bf #1}}
$$
:::

对于使用 MathJax（默认）处理的 HTML 数学过程，您可以使用 \def, \newcommand, \renewcommand, \newenvironment, \renewenvironment 和 \let 命令创建自己的宏和环境。

图表

Quarto 本机支持嵌入 Mermaid 和 Graphviz图表。这样，您就可以使用受 markdown 启发的纯文本语法创建流程图、序列图、状态图、甘特图等。

例如，这里我们嵌入了一个使用 Mermaid 创建的流程图：

```{mermaid}
flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]
```

flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]

更多信息，请参阅 图表 一文。

视频

您可以使用 {{< video >}} 简码在文档中加入视频。例如，这里我们嵌入了一段 YouTube 视频：

{{< video https://www.youtube.com/watch?v=_f3latmOhew >}}

视频可以是指视频文件（如 MPEG），也可以是指向 YouTube、Vimeo 或 Brightcove 上发布的视频的链接。了解更多信息，请参阅视频一文。

Page Breaks

pagebreak 简码使您能够在文档中插入本地分页符（例如，在 LaTeX 中是\newpage，在 MS Word 中是 docx 原生分页符，在 HTML 中是 page-break-after: always CSS 指令等）:

page 1

{{< pagebreak >}}

page 2

原生分页符支持 HTML、LaTeX、Context、MS Word、Open Document 和 ePub（对于其他格式，插入表格缩进字符 \f ）。

Divs and Spans

您可以使用 div 和 Spans 为内容区域添加类、属性和其他标识符（您将在下面的 [Callout Blocks] 中看到这方面的示例）。

例如，在这里我们使用 div (:::) 为内容区域添加 “border”类：

::: {.border}
该内容可使用边框样式
:::

转换为 HTML 后，Quarto 会将markdown翻译成:

<div class="border">
  <p>该内容可使用边框样式</p>
</div>

分隔符以至少包含三个连续冒号和一些属性的栅栏开始。属性后面可以选择另一串连续的冒号。分隔符以另一行结束，该行至少包含三个连续冒号。分隔符应与前后区块用空行隔开。分隔符也可以嵌套。例如

::::: {#special .sidebar}

::: {.warning}
在此提出警告。
:::

更多内容.
:::::

转换为 HTML 后，Quarto 会将markdown翻译成:

<div id="special" class="sidebar">
  <div class="warning">
    <p>在此提出警告。</p>
  </div>
  <p>更多内容.</p>
</div>

没有属性的标签栏总是要闭合。与围栏代码块不同，结束围栏中的冒号数量不需要与开始围栏中的冒号数量匹配。但是，使用不同长度的标签栏来区分嵌套 div 与其父级，有助于提高视觉清晰度。

括号内的内联序列（用于开始链接）Span如果紧随其后的是属性，则将被视为带有属性：

[This is *some text*]{.class key="val"}

转换为 HTML 后，Quarto 会将标记符翻译成：

<span class="class" data-key="val">
  This is <em>some text</em>
</span>

通常情况下，您会使用 CSS 和/或 过滤器以及 Divs 和 Spans 在渲染的文档中提供样式或其他行为。

属性排序

Pandoc 中的 div 和 spans 都可以拥有标识符、类和（可能有很多）键值属性的任意组合。为了让 Pandoc 识别这些属性，必须按照特定顺序提供：标识符、类，然后是键值属性。这些属性中的任何一个都可以省略，但如果提供了，则必须遵循该顺序。例如，以下内容是有效的：

[This is good]{#id .class key1="val1" key2="val2"}

但是，Pandoc 将无法识别下列：

[This does *not* work!]{.class key="val" #id}

这种排序限制同时适用于 div 和 spans。更多详情，请参阅 Pandoc 的 Divs and Spans 文档。

标注块

Markdown 语法

:::{.callout-note}
请注意，有五种类型的标注，包括
`note`, `tip`, `warning`, `caution`, and `important`.
:::

Output

注解

请注意，有五种类型的标注，包括 note, tip, warning, caution, and important.

更多信息，请参阅 Callout Blocks 一文。

其余标注块

Markdown Syntax	Output
> Blockquote	Blockquote
::: {.classname} Div :::	Div
| Line Block | Spaces and newlines | are preserved	Line Block    Spaces and newlines    are preserved

特殊字符

Markdown Syntax	Output
endash: --	endash: –
emdash: ---	emdash: —

快捷键

kbd 简码可用于在文档中描述键盘快捷方式。在 Javascript 格式中，它将尝试检测格式的操作系统并显示正确的快捷方式。在打印格式中，它将打印所有操作系统的键盘快捷方式信息。

例如，编写以下标记符：

打印，请按 {{< kbd Shift-Ctrl-P >}}. 打开现有的新项目，请按 {{< kbd mac=Shift-Command-O win=Shift-Control-O linux=Shift-Ctrl-L >}}.

将键盘快捷键显示为：

打印，请按 Shift-Ctrl-PShift-Ctrl-P. 打开现有的新项目，请按 press .