Quarto 入门指南：从安装到与 Obsidian 结合

Quarto 是一款现代化的文档创作工具，支持 Markdown 语法输出 HTML、PDF、Word 等多种格式。本文面向初学者，介绍从安装到实战的核心用法。

快速开始

安装与基础命令

在终端执行以下命令即可开启实时预览和最终渲染：

quarto preview hello.qmd  # 开启带热重载的实时预览
quarto render hello.qmd   # 渲染输出最终文件

文件头部配置

在 .qmd 文件顶部使用 YAML 设置文档元数据和输出格式：

---
title: "文档标题"
format:
  html:
    theme: cosmo
    toc: true
    toc-depth: 3
    number-sections: true
  pdf:
    documentclass: article
    margin-left: 20mm
---

模板与主题配置

Quarto 内置多种主题（darkly、flatly、sketchy 等），只需修改 YAML 中的 theme 字段即可一键切换。

PDF 输出推荐使用 Typst 渲染，速度极快：

format:
  typst:
    margin:
      x: 1.25in
      y: 1.25in

图片与交叉引用

Quarto 通过特定前缀（图片用 fig-，表格用 tbl-）配合 #id 语法实现自动编号引用。使用 @id 在正文中插入引用。

单图题注：

![这是一只可爱的小象](images/elephant.jpg){#fig-elephant}

渲染效果：

如图所示，大象非常壮观。

双图并排：

::: {layout-ncol=2}
![图一](images/img1.jpg){#fig-img1}

![图二](images/img2.jpg){#fig-img2}
:::

渲染效果：

::: {layout-ncol=2}

:::

表格样式

Quarto 支持标准 Markdown 管道表格，通过冒号 : 控制对齐方式：

| 左对齐 | 居中对齐 | 右对齐 |
| :--- | :---: | ---: |
| 内容 A | 内容 B | 内容 C |
| 内容 D | 内容 E | 内容 F |

: 这是一张带有题注的表格 {#tbl-letters}

渲染效果：

左对齐	居中对齐	右对齐
内容 A	内容 B	内容 C
内容 D	内容 E	内容 F

文中引用示例：请参阅上表。

如需将题注置于表格上方，可在 YAML 中添加 tbl-cap-location: top。

Python 脚本集成

Quarto 原生支持 Jupyter 内核运行 Python，可直接在文档中嵌入代码和执行结果。

安装依赖：

python3 -m pip install jupyter matplotlib pandas

使用 #| 语法在代码块内设置 Chunk Options：

#| label: fig-line-plot
#| fig-cap: "使用 Python 生成的折线图"
#| echo: true
#| eval: true
#| warning: false

import matplotlib.pyplot as plt
plt.plot([1, 2, 3, 4])
plt.show()

参数说明：

• echo: 是否显示源码
• eval: 是否执行代码
• warning: 是否隐藏警告

Obsidian 工作流

Obsidian 强大的本地笔记能力结合 Quarto 的渲染输出，是沉浸式写作的理想组合。由于 Quarto 文件后缀是 .qmd，默认情况下 Obsidian 无法识别，可通过以下插件解决：

方案一：qmd as md 插件（推荐）

在 Obsidian 社区插件中搜索安装 qmd as md（或通过 BRAT 安装）。启用后，Obsidian 会将 .qmd 文件视作普通笔记，支持双链引用、标签管理和图谱查看，不影响 Quarto 渲染。

方案二：Obsidian to Quarto Exporter

如果希望保持 .md 格式，可使用该插件，在需要发布时自动将 .md 导出为兼容的 Quarto .qmd 文件。

小结

Quarto 以简洁的 Markdown 语法实现了多格式输出的强大能力，配合 Obsidian 使用可以兼顾日常笔记和正式发布的需求。上手门槛低，建议从修改主题样式开始尝试。