理解 Quarto 的交叉引用机制
quarto 提供了强大的交叉引用功能，允许用户轻松引用文档中的图表、表格、章节、方程式等元素。这些引用通过 @label 的形式实现，quarto 在渲染时会自动替换为相应的编号和链接。然而，quarto 的默认交叉引用机制主要作用于一个编译单元内部。这意味着，如果一个图表 (#fig-a) 定义在一个独立的 .qmd 文件中，而另一个 .qmd 文件试图直接引用它，quarto 的渲染引擎将无法在当前编译上下文中找到该标签，从而导致引用失败。
对于像 Quarto Book 这样的多文件项目，其内部有特定的机制来管理跨章节的引用。但在处理两个独立的、非项目关联的 .qmd 文件时，我们需要一种不同的策略来“合并”它们的上下文。
跨文档引用图表的挑战
考虑以下场景：您有一个主文章 article.qmd，希望引用一个定义在 _annex.qmd 文件中的图表。
article.qmd (尝试引用外部图表):
参见附录中的图 @fig-a 以获取详细信息。
_annex.qmd (定义图表):
{#fig-a}如果直接编译 article.qmd，Quarto 将无法解析 @fig-a，因为它在 article.qmd 的本地上下文中并不存在。
解决方案：利用 include 短代码
解决这个问题的关键在于 Quarto 的 include 短代码。{{< include filename.qmd >}} 允许您将一个外部文件的内容直接嵌入到当前文档中，就好像这些内容本来就在当前文档一样。当 Quarto 渲染主文档时，它会首先将所有 include 指令替换为相应文件的实际内容，然后才进行后续的解析和编译。
通过这种方式，定义在 _annex.qmd 中的图表及其标签 (#fig-a) 将在渲染 article.qmd 时被有效地拉入 article.qmd 的编译上下文，从而使交叉引用能够正确解析。
实施步骤
-
准备包含图表的 .qmd 文件 (例如 _annex.qmd)： 创建或修改您的附录文件，确保图表带有唯一的标签。通常，为了表明这是一个被包含的文件，我们会在文件名前加上下划线（例如 _annex.qmd），但这并非强制要求。
_annex.qmd:
--- title: "附录A：示例图表" --- 这是一个在附录中定义的示例图表。 {#fig-a width="300"} 图 @fig-a 展示了 Quarto 的 Logo。注意：_annex.qmd 内部可以包含完整的 Markdown 内容，包括 YAML 头，但通常为了被包含，我们会省略 YAML 头或只保留必要的元数据。
-
在主文档中引用并包含附录文件 (例如 article.qmd)： 在您希望引用图表的主文档中，使用 {{< include >}} 短代码将 _annex.qmd 的内容引入。通常，您会将附录内容放在主文档的末尾，或者在适当的章节。
article.qmd:
--- title: "我的 Quarto 文章" format: html --- # 引言 本文将探讨 Quarto 的一些高级功能。 # 内容 我们在附录中提供了一个详细的示例图。参见附录中的图 @fig-a 以获取详细信息。 # 结论 Quarto 的 `include` 功能非常实用。 # 附录 {{< include _annex.qmd >}} -
编译主文档： 使用 Quarto 编译 article.qmd。
quarto render article.qmd
编译完成后，article.qmd 生成的 HTML、PDF 或其他格式文档中，@fig-a 将被正确解析为图表的编号和链接。
机制详解与注意事项
- 编译流程： 当 article.qmd 被渲染时，Quarto 会在处理 Markdown 内容之前，将 {{< include _annex.qmd >}} 替换为 _annex.qmd 的全部内容。这意味着，在 Quarto 的交叉引用解析阶段，#fig-a 标签已经存在于 article.qmd 的“虚拟”文档树中，因此可以被成功引用。
- 文件命名约定： 习惯上，被 include 的文件通常以 _ 开头（例如 _partial.qmd），这表明它们是局部文件，不应被独立渲染。这有助于组织项目结构。
- 路径问题： include 短代码中的文件路径是相对于当前 .qmd 文件的。如果被包含的文件在子目录中，需要提供正确的相对路径。
- 重复标签： 尽管 include 使得跨文件引用成为可能，但最终所有内容都合并到一个文档中。因此，所有标签（图表、表格、章节等）在合并后的文档中必须是唯一的。如果 article.qmd 和 _annex.qmd 都定义了 #fig-a，将会导致冲突。
- 代码块包含： include 不仅限于 Markdown 内容，也可以用于包含代码块。例如，{{< include my_code.R >}} 可以将 R 脚本文件内容作为代码块嵌入。
- 替代方案（Quarto Book/Project）： 对于大型、多章节的项目，Quarto Book 或 Quarto Project 提供了更高级的结构化方式和跨章节引用机制，它们是为管理大量文件而设计的。本文介绍的 include 方法更适用于在非项目结构下，需要将特定内容块从外部文件拉入主文档的场景。
总结
在 Quarto 中实现跨独立文档的图表交叉引用，不能依靠 Quarto 默认的“外部”引用机制。核心的解决方案是巧妙地利用 {{< include >}} 短代码。通过将包含图表定义的 .qmd 文件内容嵌入到主文档中，我们有效地将所有相关的标签带入同一个编译上下文，从而使 Quarto 的交叉引用功能能够无缝工作。这种方法提供了一种灵活且强大的方式来模块化您的 Quarto 文档内容，同时保持完整的引用能力。
