pkgdown生成的网站中.Rd文件公式无法正常渲染问题咨询

架构老林

2026-6-20

可能的问题及排查方向

Rd文件公式语法不规范：检查.Rd文件里\eqn{}或\deqn{}的语法是否符合Rd文档标准，比如公式内的特殊字符是否正确转义、括号是否配对完整，避免公式前后出现多余空格或无效字符。
pkgdown版本兼容性问题：旧版本pkgdown对Rd文件中LaTeX公式的解析可能存在bug，执行install.packages("pkgdown")升级到最新稳定版后，重新生成网站。
MathJax配置层级错误：确认_pkgdown.yml里的MathJax配置结构是否正确，正确的写法应该是：
```
template:
  params:
    mathjax: true
```
若直接写成template: mathjax: true会导致配置不生效，检查文件的缩进和层级是否符合YAML规范。
公式环境误用：\eqn{}用于行内公式，\deqn{}用于块级公式，pkgdown对两者的解析逻辑有差异，尝试调整公式对应的环境，或确保Rd文件中公式环境的写法符合pkgdown的解析要求。
缓存残留问题：pkgdown会缓存生成的页面内容，之前的错误渲染结果可能被保留，先执行pkgdown::clean_site()清理缓存，再重新运行pkgdown::build_site()生成新内容。
Rd文件编码异常：如果Rd文件使用非UTF-8编码，可能导致公式解析失败，确保文件保存为UTF-8编码格式。