Markdown 引用语法教程

写技术文档或学术文章的时候，经常需要在正文中标注"这句话引自某篇论文"或"这个数据来源于某个报告"。Markdown 本身没有专门的引用（citation）语法，但通过 Markdown 脚注和 Pandoc 扩展，可以实现从简单的文献标注到完整的参考文献管理。

这篇文章就来讲 Markdown 里怎么做引用——包括最基础的脚注引用法，以及更专业的 Pandoc citation 语法。

脚注引用：最简单的方法

如果你只是偶尔需要在文章里加几条引用，用 Markdown 脚注就够了。把引用内容直接写进脚注定义里：

这项研究表明，代码审查能有效减少缺陷率。[^smith2020]

[^smith2020]: Smith, J. (2020). *Code Review Practices in Large-Scale Software Development*. IEEE Software, 37(4), 78-85.

渲染后，正文会出现一个上标数字 ¹，点击后跳到页面底部的参考文献说明。

这种方式的好处是简单直观，GitHub、GitLab、Obsidian、Typora 这些平台都支持 [^1] 脚注语法。坏处是——你得手动维护引用格式，比如每条参考文献的 APA 格式都要自己拼。

说实话，引用不超过五六条的时候，用脚注完全没问题。但要是写一篇有几十条引用的论文或者长篇技术报告，手动管理格式就是噩梦了。这就是 Pandoc citation 发挥作用的地方。

Pandoc Citation 语法：@key 引用

Pandoc 是一个强大的文档转换工具，它扩展了 Markdown，增加了专门用于学术引用的语法。核心就是 @ 符号。

基本用法

在正文里用 @citationKey 引用文献：

代码审查对软件质量有显著影响 [@smith2020]。

根据 @smith2020 的研究，代码审查能减少 60% 的缺陷。

两种写法的区别：

[@smith2020] — 括号引用（parenthetical），渲染为 (Smith, 2020)
@smith2020 — 叙述引用（narrative），渲染为 Smith (2020)，适合融入句子

添加前缀和后缀

括号引用里可以加前缀和后缀：

多项研究证实了这一点 [见 @smith2020; 也参考 @jones2019, 第 3 章]。

数据显示增长了 30% [@smith2020, p. 45]。

渲染效果：

(见 Smith, 2020; 也参考 Jones, 2019, 第 3 章)
(Smith, 2020, p. 45)

引用多篇文献

用分号隔开：

[@smith2020; @jones2019; @wang2021]

渲染后按你指定的引用样式排列，比如 APA 格式会变成 (Jones, 2019; Smith, 2020; Wang, 2021)。

隐藏作者只显示年份

有时候你已经提到了作者名字，只想显示年份：

Smith 指出 [-@smith2020] 代码审查非常关键。

-@ 会省略作者，只渲染 (2020)。

准备 BibTeX 文件

Pandoc citation 的关键是 .bib 文件——一个纯文本的参考文献数据库。每条记录长这样：

@article{smith2020,
  author  = {Smith, John},
  title   = {Code Review Practices in Large-Scale Software Development},
  journal = {IEEE Software},
  volume  = {37},
  number  = {4},
  pages   = {78--85},
  year    = {2020}
}

@book{jones2019,
  author    = {Jones, Mary},
  title     = {Software Quality Assurance},
  publisher = {Springer},
  year      = {2019}
}

花括号里的 smith2020、jones2019 就是你在正文中用的 citation key。命名规则是"作者+年份"或任意有意义的字符串，只要正文和 .bib 文件里的 key 对得上就行。

这里我踩过一个坑：有一回从 Zotero 导出 BibTeX 文件，结果 citation key 里带了空格（比如 @smith 2020），Pandoc 死活不识别。后来统一把 key 改成无空格的格式（smith2020）就好了。如果你也从 Zotero 导出，建议装一个 Better BibTeX 插件，它会自动生成规范的 citation key。

获取 BibTeX 的几种方式

来源	操作
Google Scholar	搜索文献 → 点引号按钮 → 选 BibTeX
Zotero	安装 Better BibTeX 插件 → 右键导出
Mendeley	选文献 → File → Export → BibTeX
手写	按格式直接创建 .bib 文件

用 Pandoc 生成参考文献

有了 .md 文件和 .bib 文件，用一条命令就能生成带参考文献的文档：

pandoc document.md \
  --citeproc \
  --bibliography=refs.bib \
  -o output.pdf

关键参数说明：

--citeproc — 启用引用处理（替代了旧版的 --filter pandoc-citeproc）
--bibliography=refs.bib — 指定 BibTeX 文件路径
-o output.pdf — 输出格式（也可以是 .html、.docx 等）

Pandoc 会自动：

把正文里的 @key 替换为格式化的引用标注
在文末生成完整的参考文献列表（References）
正文引用和参考文献列表自动关联

指定引用样式

用 --csl 参数可以切换引用格式：

pandoc document.md \
  --citeproc \
  --bibliography=refs.bib \
  --csl=apa.csl \
  -o output.pdf

CSL（Citation Style Language）文件可以从 Zotero Style Repository 免费下载，支持超过一万种样式。常见的几种：

样式	文件	领域
APA 7th	`apa-7th-edition.csl`	社会科学、心理学
IEEE	`ieee.csl`	工程、计算机科学
Chicago	`chicago-author-date.csl`	人文学科
MLA 9th	`modern-language-association.csl`	语言、文学

引用工具链对比

除了直接用 Pandoc，还有几个工具链也支持 Markdown 引用：

工具	引用语法	文献格式	特点
Pandoc	`@key`	BibTeX / CSL	最通用，命令行工具
Quarto	`@key`	BibTeX / CSL	基于 Pandoc，更易用，支持交互文档
R Markdown	`@key`	BibTeX / CSL	R 语言生态，适合数据分析
Jekyll Scholar	`{% cite key %}`	BibTeX	Jekyll 博客专用
MyST	`@key` / DOI 链接	BibTeX	支持 DOI 自动识别

Quarto 是 Pandoc 的上层封装，语法完全一样，但配置更简单。如果你不想折腾命令行参数，Quarto 是个不错的选择——在 _quarto.yml 里配好 bibliography 和 csl 就行，连 pandoc 命令都不用手动敲。

脚注 vs 引用：什么时候用哪个

这两个东西容易搞混，简单说一下区别：

特性	脚注 `[^1]`	引用 `@key`
用途	补充说明、备注、简单引用	学术引用、参考文献管理
格式管理	手动	自动（通过 CSL 样式）
参考文献列表	不自动生成	自动生成
适用平台	GitHub、GitLab、Obsidian 等	Pandoc、Quarto、R Markdown
复杂度	低	中

我的建议是：

写博客、README、技术文档 → 用脚注 [^1]，简单够用
写论文、研究报告、书籍 → 用 Pandoc citation @key，自动管格式
在 GitHub 上讨论学术问题 → 用脚注手动写引用格式（GitHub 不支持 Pandoc citation）

常见问题

GitHub 上能用 @key 引用吗？

不能。GitHub 的 Markdown 渲染器不支持 Pandoc citation 语法。在 GitHub 上做引用，只能用脚注方式：

根据研究[^1]，这个方案可行。

[^1]: Smith, J. (2020). *Code Review Practices*. IEEE Software, 37(4), 78-85.

Pandoc 提示找不到 citation key 怎么办？

检查这几点：

.bib 文件里的 key 和正文里的 @key 是否完全一致（区分大小写）
--bibliography 参数指定的文件路径是否正确
.bib 文件的语法是否有误（多余的逗号、缺少花括号等）

怎么在 Obsidian 里做学术引用？

Obsidian 原生只支持脚注 [^1]，不认识 Pandoc 的 @key 语法。但可以装社区插件来解决：

Pandoc Plugin — 在 Obsidian 里直接调用 Pandoc 导出带引用的文档
Citations Plugin — 连接 Zotero 数据库，在 Obsidian 里搜索和插入引用

引用样式怎么改？

改 --csl 参数指向的 .csl 文件就行。比如从 APA 改成 IEEE：

pandoc doc.md --citeproc --bibliography=refs.bib --csl=apa.csl -o output.pdf

# IEEE 格式
pandoc doc.md --citeproc --bibliography=refs.bib --csl=ieee.csl -o output.pdf

同样的正文，换个 CSL 文件，输出的引用格式和参考文献列表就会自动调整。

参考来源

Pandoc 官方文档 — Citations — Pandoc citation 语法的权威参考
Quarto 官方文档 — Citations & Footnotes — Quarto 引用系统说明
CSL 项目 — Citation Style Language — 引用样式语言规范
Markdown Guide — Extended Syntax: Footnotes — Markdown 脚注语法社区参考
Zotero Style Repository — 超过一万种 CSL 引用样式下载