如何在Docfx 2.58.0构建生成的Index.html页面中添加TOC目录

修复步骤 #

1. 修正目录配置文件格式与内容

首先将articles目录下的toc.md重命名为toc.yml，按如下格式编写内容：

- name: 介绍
  href: intro.md

修改项目根目录（docfx.json同级）的toc.yml，关联所有子目录的toc文件：

- name: 文档教程
  href: articles/toc.yml
  homepage: articles/intro.md
- name: 接口文档
  href: api/toc.yml
  homepage: api/index.md

api目录下的toc.yml保持自动生成或手动按上述格式配置即可。

2. 校验docfx.json配置

确认docfx.json的build节点包含以下配置，避免遗漏toc文件、模板配置错误：

{
  "build": {
    "content": [
      {
        "files": [
          "**/*.md",
          "**/*.yml"
        ],
        "exclude": [
          "_site/**",
          "bin/**",
          "obj/**"
        ]
      }
    ],
    "resource": [
      {
        "files": [
          "images/**"
        ]
      }
    ],
    "template": [
      "default",
      "modern"
    ],
    "globalMetadata": {
      "_appTitle": "你的文档站点名称",
      "_enableSearch": true
    },
    "output": "_site"
  }
}

3. 解决版本冲突问题

本地全局安装的docfx版本和VS项目中docfx.console NuGet包版本不一致会导致构建异常，执行命令dotnet tool uninstall -g docfx卸载全局版本，之后仅通过Visual Studio右键项目生成的方式构建文档产物即可，无需使用全局docfx命令，也能避免docfx serve的代理访问问题。

4. 受限网络适配

如果是网络限制导致模板资源加载失败，可提前下载docfx的默认模板与modern模板到本地目录，在docfx.json的template节点直接填写本地模板的绝对/相对路径即可，无需拉取远程资源。

所有配置修改完成后，删除旧的_site目录，重新在VS中构建项目即可看到左侧TOC导航栏。

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