Quarto 文档间图表交叉引用：利用 include 实现内容整合-Python教程-PHP中文网

Quarto 文档间图表交叉引用：利用 include 实现内容整合

花韻仙語

发布： 2025-09-24 10:02:01

原创

198人浏览过

Quarto 文档间图表交叉引用：利用 include 实现内容整合

本文探讨在 Quarto 独立文档中实现跨文件图表交叉引用的方法。由于 Quarto 默认的交叉引用机制仅限于单一编译单元，直接引用外部文件中的标签无法成功。核心解决方案是利用 {{< include >}} 短代码将包含图表定义的 .qmd 文件内容嵌入到主文档中，从而使所有引用标签在渲染时处于同一上下文，实现准确的交叉引用。

理解 Quarto 的交叉引用机制

quarto 提供了强大的交叉引用功能，允许用户轻松引用文档中的图表、表格、章节、方程式等元素。这些引用通过 @label 的形式实现，quarto 在渲染时会自动替换为相应的编号和链接。然而，quarto 的默认交叉引用机制主要作用于一个编译单元内部。这意味着，如果一个图表 (#fig-a) 定义在一个独立的 .qmd 文件中，而另一个 .qmd 文件试图直接引用它，quarto 的渲染引擎将无法在当前编译上下文中找到该标签，从而导致引用失败。

对于像 Quarto Book 这样的多文件项目，其内部有特定的机制来管理跨章节的引用。但在处理两个独立的、非项目关联的 .qmd 文件时，我们需要一种不同的策略来“合并”它们的上下文。

跨文档引用图表的挑战

考虑以下场景：您有一个主文章 article.qmd，希望引用一个定义在 _annex.qmd 文件中的图表。

article.qmd (尝试引用外部图表):

参见附录中的图 @fig-a 以获取详细信息。

登录后复制

_annex.qmd (定义图表):

![图表的标题](path/to/figure.png){#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 的编译上下文，从而使交叉引用能够正确解析。

Calliper 文档对比神器

文档内容对比神器

查看详情

实施步骤

准备包含图表的 .qmd 文件 (例如 _annex.qmd)： 创建或修改您的附录文件，确保图表带有唯一的标签。通常，为了表明这是一个被包含的文件，我们会在文件名前加上下划线（例如 _annex.qmd），但这并非强制要求。

_annex.qmd:
```
---
title: "附录A：示例图表"
---

这是一个在附录中定义的示例图表。

![Quarto Logo 示例图](https://quarto.org/quarto.png){#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 文档内容，同时保持完整的引用能力。

以上就是Quarto 文档间图表交叉引用：利用 include 实现内容整合的详细内容，更多请关注php中文网其它相关文章！