Quarto 文档创作语法

Quarto
作者

yangjh

发布日期

2023年7月2日

创作Quarto文档时，除了markdown文档支持的特性外，还支持如下特性，详情参见：https://quarto.org/docs/authoring/markdown-basics.html。

文献引用

Quarto 主要面向学术生产及技术创作群体，对参考文献的支持非常全面。要在Quarto文档中使用参考文献，需要提供参考文献内容并使用合适的方式进行引用，然后在指定的地方生成参考文献。

指定参考文献

参考文献可以使用Zotero进行生成，后缀名通常为.bib。Quarto 使用bibliography字段，为文档指定参考文献的名称及所在位置，还可以在Quarto配置文件中以YAML数组的方式提供多个文献。

  1. 可以在项目设置文档_quarto.yml中使用bibliography设置参考文献，参见1；
  2. 还可以在项目下的某个文件夹设置文档中_metadata.yml使用bibliography设置参考文献;
  3. 在文档YAML元数据区，使用bibliography字段提供参考文献名称。

引用文献

在合适的地方，使用语法类似[@danesi2004]进行引用，

例如：(Danesi 2004)

设定引用样式

在项目设定文件中，通过csl选项设定引用样式。但是大多数中文csl使用了CSL-M语法，而目前版本的Pandoc并不支持CSL-M语法解析，故当使用中文csl时会报错。详见https://github.com/quarto-dev/quarto-cli/discussions/4598

---
title: "My Document"
bibliography: references.bib
csl: nature.csl
---

生成参考文献

使用区块标记，可以指定参考文献生成的容器。


::: {#refs}
:::

脚注

使用[^2]这样的语法插入脚注2。脚注的内容还可以是多行3，参见https://quarto.org/docs/authoring/footnotes-and-citations.html#fn2

增强表格

指定表格对齐方式

Demonstration of pipe table syntax
Default Left Right Center
12 12 12 12
123 123 123 123
1 1 1 1

使用Bootstrap样式

| fruit  | price |
| ------ | ----- |
| apple  | 2.05  |
| pear   | 1.37  |
| orange | 3.09  |

: Fruit prices {.striped .hover}

效果如下：

Fruit prices
fruit price
apple 2.05
pear 1.37
orange 3.09

设定列宽度

默认的markdown中，是无法设定列宽的。但在.qmd中，可以使用类似{tbl-colwidths="[75,25]"}的语句，指定表格各列的宽度。

| fruit  | price |
| ------ | ----- |
| apple  | 2.05  |
| pear   | 1.37  |
| orange | 3.09  |

: Fruit prices {tbl-colwidths="[75,25]"}

效果如下：

Fruit prices
fruit price
apple 2.05
pear 1.37
orange 3.09

其他特性

Quarto中的表格，还可以使用代码生成、也可使用html生成。详见：https://quarto.org/docs/authoring/tables.html#computations

内嵌视频

使用如下语法，可以在文档中内嵌视频（目前仅支持本地mp4、YouTube、Vimeo、BrightCove）：

{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}

Quarto支持设置视频的播放位置、比例等功能，详见：https://quarto.org/docs/authoring/videos.html。

如果要插入B站的视频，可以采用嵌入代码的方式进行：

详细设置可参考：https://www.zeromes.cn/archives/%e7%a0%94%e7%a9%b6/451

分页

使用如下语法，可以在文档转化为word、pdf等格式时，进行分页。

page 1

{{< pagebreak >}}

page 2

区块

在Quarto文档中，可以添加区块或行内区块，类似与HTML中的div和span元素。

::: {.hello}
区块内容
:::

将生成一个class值为hello的div区块。snippet为div。

区块内容

区块还可以嵌套，还要内置的区块，详见：https://quarto.org/docs/authoring/markdown-basics.html#callout-blocks

注释

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

引入外部文档

使用<include>短代码，可以实现文档的复用，在文档内容实现搭积木式的组合。详见https://quarto.org/docs/authoring/includes.html

---
title: "My Document"
---

这些内容来自独立的文档。使用`< include >`包含一个文档，相当于将文档中所有的内容复制到了父文档。



Use the data...

这些内容来自独立的文档。使用< include >包含一个文档，相当于将文档中所有的内容复制到了父文档。

阻止代码运行

有时候，为了向读者展示代码，我们需要阻止代码运行。

使用````标记内容即可实现展示但不运行的目的。

````
---
title: "My document"
---

Some markdown content.

```{{python}}
1 + 1
```

Some additional markdown content.

````

设定内容布局

当内容的宽度超过默认宽度时，可通过设定布局大小的区域，比如：

:::{.column-page}
里面放图片、表格等需要增大宽度的内容
:::

运行Python代码

import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(
  subplot_kw = {'projection': 'polar'} 
)
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
图 1: A line plot on a polar axis

参考文献

Danesi, Marcel. 2004. Messages, Signs, and Meanings: A Basic Textbook in Semiotics and Communication. Toronto: Canadian Scholars’ Press.
回到顶部

脚注

  1. https://quarto.org/docs/projects/quarto-projects.html#creating-projects↩︎

  2. 这是一个脚注。↩︎

  3. 长脚注内容可以是多段。

    比如像这样。↩︎