在quarto中撰写技术文章或报告时，我们经常会将内容拆分为多个.qmd文件，例如将附录、数据源或特定章节独立存放。然而，当需要在主文档中引用位于另一个.qmd文件中的图表时，quarto的默认交叉引用机制似乎无法直接识别。这是因为quarto的交叉引用通常在单个文档或预定义的多文档项目（如书籍或网站）的统一上下文中工作。
例如，假设我们有一个主文章文件article.qmd，其中包含对某个图表的引用：
--- title: "主文章" --- # 主要内容 详细信息请参见附录中的图 @fig-a。
而这个图表实际上定义在另一个独立的附录文件annex.qmd中：
---
title: "附录"
---
# 附录 A
{#fig-a} 直接渲染article.qmd时，Quarto将无法找到@fig-a的定义，因为annex.qmd的内容并未被纳入article.qmd的渲染上下文。
解决此问题的关键在于Quarto提供的include短代码。include短代码允许我们在一个.qmd文件中嵌入另一个文件的内容。通过这种方式，我们可以有效地将附录文件的内容“合并”到主文章文件中，从而创建一个统一的文档上下文，使得交叉引用能够正确解析。
使用include短代码实现跨文档引用要实现跨文档的图表交叉引用，我们需要在主文档中引入包含目标图表的附录文档。具体步骤如下：
-
准备附录文件： 创建包含图表定义的附录文件。为了清晰起见和遵循Quarto的惯例，建议将此类被包含的文件命名为以下划线开头（例如_annex.qmd），以表明它们是部分内容，通常不单独渲染。
_annex.qmd 文件内容示例：
Teleporthq
一体化AI网站生成器，能够快速设计和部署静态网站
182
查看详情
--- # title: "附录" # 通常被包含的文件不需要独立的YAML头信息，但如果有，Quarto会忽略除了内容之外的部分 --- # 附录 A {#fig-a}请注意，path/to/figure.png应替换为实际的图片路径。为了示例清晰，这里假设图片位于images/目录下。
-
在主文档中包含附录文件并引用： 在主文章文件article.qmd中，使用{{< include >}}短代码将_annex.qmd的内容嵌入到需要的位置。通常，这会在主文档的末尾或特定章节之后。
article.qmd 文件内容示例：
--- title: "主文章" format: html # 或pdf, docx等 --- # 主要内容 在主文章中，我们可以引用附录中的内容。例如，详细信息请参见附录中的图 @fig-a。 这个图表提供了关于某个重要趋势的直观展示。 ## 附录内容 {{< include _annex.qmd >}}当Quarto渲染article.qmd时，它会首先将_annex.qmd中的所有内容（包括图表定义![...]{#fig-a}）插入到{{< include _annex.qmd >}}所在的位置。这样一来，在整个文档的渲染过程中，@fig-a的引用就能在同一个上下文中找到其对应的定义，从而生成正确的图表编号和链接。
- 文件命名约定：如前所述，使用下划线前缀（如_annex.qmd）来命名被包含的文件是一个良好的实践。这有助于区分主文档和被包含的片段，并且在某些构建系统中，带下划线的文件默认不会被单独渲染。
- 路径管理：当使用include包含文件时，被包含文件中的相对路径（例如图片路径images/sample-figure.png）是相对于主文档的位置来解析的，而不是相对于被包含文件自身的位置。因此，在组织文件结构时需要特别注意图片或其他资源的路径设置。
- YAML头信息：被include的文件通常不需要独立的YAML头信息。即使有，Quarto在处理include时也主要关注其内容，而非其独立的元数据。主文档的YAML头信息将控制最终输出的整体配置。
- 渲染顺序：确保{{< include >}}语句出现在引用（如@fig-a）之前或至少在同一个渲染流程中。在本例中，即使include语句在引用之后，只要它们都在同一个.qmd文件中，Quarto在解析交叉引用时会扫描整个文档。
- 替代方案（书籍/项目）：对于更大型、结构更复杂的项目，例如包含多个章节或子章节的Quarto书籍或网站，Quarto提供了更高级的结构化管理方式。通过在_quarto.yml中定义章节顺序，Quarto能够自动管理跨章节的交叉引用，而无需手动使用include。本教程的方法更适用于在单个输出文档中整合来自不同源文件的内容。
通过巧妙地运用Quarto的include短代码，我们可以有效地解决在不同.qmd文件之间进行图表交叉引用的问题。这种方法将多个文件逻辑上合并为一个，为Quarto的交叉引用机制提供了一个统一的上下文，从而确保了文档内容的完整性和准确性。在管理模块化内容时，理解并应用这一技巧将大大提高Quarto文档的编写效率和灵活性。
以上就是Quarto多文档交叉引用：实现跨文件图表引用的详细内容，更多请关注知识资源分享宝库其它相关文章！
相关标签： html pdf include 大家都在看： Python怎么用Beautiful Soup解析HTML_Beautiful Soup HTML解析实战教程 python怎么解析HTML和XML_python HTML与XML解析方法 使用 BeautifulSoup 从 HTML 元素中移除指定标签 使用 BeautifulSoup 从 HTML 元素中移除特定标签 使用BeautifulSoup移除HTML元素中的特定标签
发表评论:
◎欢迎参与讨论，请在这里发表您的看法、交流您的观点。