如何在DocFX生成站点的页眉/页脚添加PDF导出下载按钮

步骤1：准备自定义模板 #

• 找到DocFX默认模板位置（通常在DocFX安装目录的templates/default下），复制其中的header.tmpl.part（修改页眉用）或footer.tmpl.part（修改页脚用）文件到你项目的templates/custom目录（无此目录则新建）。

步骤2：修改模板添加下载按钮 #

• 打开复制后的模板文件，在合适位置插入下载按钮的HTML代码：

  <a href="{{_siteRoot}}/resources/your-target.pdf" class="btn btn-primary" download>下载PDF文档</a>
  

  • 说明：
    • {{_siteRoot}}是DocFX内置变量，自动指向站点根路径，避免硬编码路径问题
    • download属性强制浏览器触发下载动作（而非直接打开PDF）
    • 可使用DocFX默认的btn系列样式类，保持站点风格统一

步骤3：配置DocFX启用自定义模板 #

• 打开项目根目录的docfx.json，在build节点的template数组中添加自定义模板路径，确保放在默认模板之后（优先级更高）：

  "build": {
    "template": [
      "default",
      "templates/custom"
    ],
    // 其他原有配置...
  }
  

步骤4：确保PDF文件被正确部署 #

• 在项目src目录下创建resources文件夹，放入已生成的PDF文件
• 在docfx.json的build->files配置中添加资源包含规则，确保生成站点时PDF被复制到输出目录：

  "build": {
    "files": [
      {
        "include": [
          "src/**/*",
          "src/resources/**"
        ]
      }
    ],
    // 其他原有配置...
  }
  

步骤5：测试验证 #

• 运行docfx build重新生成站点，打开页面后点击页眉/页脚的按钮，确认能正常下载PDF文件

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