R包发布至CRAN后Vignette缺失目录与作者信息问题排查

问题成因 #

• 核心根因为本地与CRAN的Vignette渲染规则存在差异，具体可拆解为三类原因：

1. YAML配置不匹配 #

你本地编译时大概率调用的是rmarkdown::html_document模板，你配置的作者信息、目录生成等参数仅对该模板生效；但CRAN编译包内Vignette时默认调用rmarkdown::html_vignette模板，如果你没有将author、toc: true等参数明确配置在html_vignette的output项下，这些配置不会被识别。同时html_vignette本身默认关闭目录显示、默认不渲染作者信息，需要手动显式开启对应配置。

2. CRAN的HTML后处理限制 #

CRAN会对所有包的Vignette HTML做统一标准化后处理，会剥离自定义CSS、非标准头部元数据、自定义导航元素，保证所有CRAN Vignette风格统一。如果你使用了toc_float这类html_document支持但html_vignette不兼容的参数，相关的目录元素会被直接剥离，无法正常显示。

3. 包配置缺失 #

如果你的DESCRIPTION文件中VignetteBuilder字段未明确指定rmarkdown，或是Vignette头部的VignetteEngine声明错误，CRAN会调用默认的Sweave引擎编译Rmd文件，所有rmarkdown专属的配置都会失效，也会导致目录、作者信息丢失。

内容的提问来源于stack exchange，提问作者Eric Weine