如何在DocFx中基于实际文件夹自定义导航？能否自定义api/toc.yml？

DocFx默认会按命名空间生成API导航结构，示例如下：

- MyNamespace.SomeArea
  - Class 1
  - Class 2
- MyNamespace.SomeOtherArea
  - Class 3
  - Class 4

但如果需要基于类的实际存储文件夹（与命名空间不对应）生成导航，预期结构如下：

- RootFolder/Subfolder1
  - Class 1
- RootFolder/Subfolder2
  - Class 2
  - Class 3
  - Class 4

可以通过以下步骤实现自定义导航：

1. 禁用DocFx自动生成API目录的toc.yml #

在项目的docfx.json配置文件中，找到build下的content条目，为API源文件所在的配置项添加"disableTocGeneration": true，阻止DocFx自动生成api/toc.yml。示例配置片段：

"build": {
  "content": [
    {
      "files": ["**/*.cs"],
      "src": "src",
      "dest": "api",
      "disableTocGeneration": true
    }
  ],
  // 其他构建配置...
}

2. 自定义生成api/toc.yml #

按照需求的文件夹结构手动编写或通过脚本生成api/toc.yml，格式需符合DocFx的目录规范。示例内容：

- name: RootFolder/Subfolder1
  items:
    - name: Class 1
      href: Class1.md
- name: RootFolder/Subfolder2
  items:
    - name: Class 2
      href: Class2.md
    - name: Class 3
      href: Class3.md
    - name: Class 4
      href: Class4.md

如果类的数量较多，建议编写脚本（如C#、Python脚本）遍历源代码文件夹，自动匹配类文件与生成的MD文档路径，批量生成符合要求的toc.yml。

3. 确保自定义toc.yml被识别 #

将生成好的api/toc.yml放置在DocFx项目对应API输出的目录下（即docfx.json中配置的dest路径，默认是api文件夹），DocFx构建时会读取该文件生成自定义导航结构。

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