Quarto 不完全指北 · 第二节 内容的写作

在上一篇博客中，我们已经在 VScode 中配置好了 Quarto 的工作环境，接下来我们将 Quarto 渲染一篇文档为 HTML 格式。

Quarto 采取格式与内容相分离的方式来编写文档，因此，我们写作内容的文件是一个纯文本文件，渲染（render）与格式调整是之后完成的事情。

要使用 Quarto 渲染一个文档，首先在工作空间中新建一个名为test.qmd的空文件，这个文件就是我们将在其中写作的文档。

YAML 配置

YAML 是“YAML ain't Markup Language”的循环缩写。YAML 是一种在互联网上广泛使用的用于数据存储和交换的标记语言。

Quarto 的配置选项以 YAML 的格式写在文件的最开头，上下由三个连字符“-”包裹，称为文档的“Metadata”，你如果熟悉 Pandoc 标准的 Markdown，对这种配置格式应该不感到陌生。

关于 YAML 的说明将在下一篇博客中提及，现在我给出一个可用的样例用于编写我们的文件。

---
lang: zh
format: 
  html: default
---

这是一个正确的 Metadata 写法。其意义是令模板使用中文，并用默认配置将文档输出为 HTML 格式。现在你应该将这段代码复制进你的文档中。以便后续的预览和渲染。

预览和渲染文档

下载了 Quarto 扩展以后，在 VScode 中打开 qmd 文件，页面的右上角会有一个 Preview 按钮，点击可以进行预览，在一般的屏幕上上会打开预览的 HTML 文件。

自带的预览脚本对于 HTML 输出的支持是很好的，但是对于其他的文件格式就不那么完美了。按 ctrl+反引号打开终端，或使用 cmd，执行下面的命令

quarto preview src

其中，src是目标文件的地址。

就会开启一个预览进程，只要终端不被关闭或进程不被停止，Quarto 就会监控文件的更改并实时预览文件，还可以在终端中查看渲染失败的错误信息。

要渲染文件，只需要把上面命令的 preview 换成 render 即可，即

quarto render src

现在，预览你的文档并尝试下面学习下面的写作语法。

基本的 Markdown 和 GFM 语法

Markdown 是一种轻量级的标记语言。使用 Markdown，你可以完全将格式抛诸脑后，完全将注意力集中在内容的写作上，这篇博客的写作就是使用 Markdown 完成的。

你可以在 Markdown 官方教程中学习到 Markdown 的基本语法和扩展语法。

Quarto 也完全支持 GFM 的所有语法，你可以查看 GFM 的一个中文文档来学习 GFM 的语法。GFM 是 Markdown 的一个方言，为 Markdown 添加了很多有用的特性，在此不多赘述。

Quarto-Pandoc 专用的的 Markdown 语法

Quarto 还有拥有许多 GFM 不包括和不支持的语法，诸如网格式表格、图表和公式编号、以及引用等等，可以在官方教程查看完整的教程，这里列出几个常用的。

容器（div 和 span）

Quarto 中支持用三个或更多的英文冒号包裹一段内容，这定义了一个容器。

例如这样

:::{#text .smaller}
Some text
:::

这与以下 HTML 代码相同

<div id="text" class="smaller">
  Some text
</div>

容器之间可以嵌套，只要使用的冒号个数不一样多即可。

大括号也可以单独使用，为一些元素添加属性，例如

![alt](imgsrc){#text}

这代表一张 ID 为 text 的图片。

Quarto 中有一些预定义的样式，例如上面的 smaller 就可以将元素变得更小。

标注块

将容器类名定义为

• callout-note
• callout-tip
• callout-warning
• callout-important
• callout-caution

中的一种，就可以得到标注块，例如这样

:::{.callout-note}
## This is a note for you

Note that there are five types of callouts, including: 
`note`, `tip`, `warning`, `caution`, and `important`.
:::

就会得到

注意，我们使用了一个二级标题改变了标注块的标题。

交叉引用

可以使用容器和大括号对几乎所有的元素进行编号以便交叉引用，例如定理、公式图表等，只要定义它们的 ID 即可。

例如

:::{#thm-Pythagorean}
## 勾股定理

在直角三角形ABC中，C为直角，角的对边分别为a,b,c，则它们满足下列关系
$$
a^2+b^2=c^2
$$
:::

这将渲染出以下效果

注意，ID 前必须带有对应的类名如 thm, eq, pf, tbl 等，并且标题被渲染成了定理的名字。

对于全部的类名，参见官方文档。

要进行引用，只需要写下@thm-Pythagorean，这将得到一个完整的引用。

要进行自定义引用前缀，需要写[公式 @thm-Pythagorean]，这将得到公式 1 而不是定理 1。

要进行无前缀引用，需要写[-@thm-Pythagorean]，注意 @ 前的连字符 -，这将得到单独的 1，不带任何前缀。

参考

Quarto 官网