使用pkgdown时Rmd文件公式编号与引用失效问题求助

1. 调整Rmd的YAML输出设置 #

替换原输出格式为bookdown::html_document2，同时补充vignette识别所需的元信息，修改后的YAML头如下：

output:
  bookdown::html_document2:
    toc: true
    toc_depth: 3
    number_sections: true
vignette: >
  %\VignetteIndexEntry{你的 vignette 标题}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}

2. 配置pkgdown启用bookdown处理 #

在R包根目录创建或修改_pkgdown.yml文件，添加以下内容，确保pkgdown用bookdown引擎构建vignette：

build:
  vignettes:
    builder: bookdown::html_vignette

3. 规范公式与引用的写法 #

保持公式标签的紧凑格式，避免多余空行干扰解析：

\begin{equation}
y_{t} = \beta_1 x_{1t} + \cdots + \beta_k x_{kt} + u_{t}, \qquad t=1,2,..., n
(\#eq:linear-regression-model)
\end{equation}

引用语法\@ref(eq:linear-regression-model)保持不变。

4. 重新构建pkgdown #

清理缓存后重新执行构建：

pkgdown::clean_site()
pkgdown::build_site()

原理说明 #

pkgdown默认用基础rmarkdown引擎处理vignette，无法识别bookdown的交叉引用逻辑。通过指定bookdown的输出格式和构建器，能让pkgdown在渲染时启用bookdown的公式编号与引用解析功能，解决本地正常但构建失效的问题。

内容的提问来源于stack exchange，提问作者Moritz Schwarz