docFX API参考目录移除命名空间前缀的实现方法

你完全不需要写额外的服务器端构建脚本，docFX本身就支持通过配置和自定义模板来实现「TOC移除命名空间前缀、标题/页眉保留完整前缀」的需求，下面是具体的实现步骤：

方法一：元数据转换+自定义模板分离显示逻辑（推荐） #

这是最优雅的方案，既能精准控制TOC和页面内容的显示差异，又不需要修改生成后的文件：

1. 新增简化版命名空间元数据 #

在你的docfx.json的build节点下，给内容添加transform规则，专门为命名空间生成一个去掉前缀的简化字段：

"build": {
  "content": [
    {
      "files": ["**/*.csproj"],
      // 新增shortNamespace字段，存储去掉前缀后的命名空间
      "transform": {
        "shortNamespace": "replace(@namespace, 'MyBiz.CRM.Sales.', '')"
      }
    }
  ],
  // 保留其他原有配置...
}

2. 自定义模板修改TOC渲染逻辑 #

docFX的默认模板可以复制出来修改，实现TOC和页面标题的差异化显示：

• 从docFX默认模板目录（通常是%USERPROFILE%\.docfx\templates\default）复制toc.html到你项目的自定义模板目录（比如templates/custom）
• 修改toc.html中渲染命名空间的代码：将原来的{{item.name}}替换为{{item.shortNamespace || item.name}}，这样TOC就会显示简化后的命名空间
• 保留页面标题、页眉的渲染逻辑（比如header.html或API详情页模板）仍使用{{item.name}}，确保完整前缀显示在页面顶部

3. 指定自定义模板生成文档 #

在docfx.json的build节点中添加template配置，指向你的自定义模板：

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

方法二：直接在模板中做字符串替换（快速实现） #

如果不想新增元数据字段，也可以跳过第一步，直接在自定义模板的toc.html中做字符串替换：
把渲染命名空间的{{item.name}}代码替换为{{item.name.replace('MyBiz.CRM.Sales.', '')}}，这样TOC会直接去掉前缀，页面其他部分的命名空间渲染仍用原始的{{item.name}}即可。

备选方案：Post-Build脚本（不推荐） #

如果以上方法因为项目特殊配置无法生效，再考虑用Post-Build脚本（比如PowerShell、Node.js）遍历生成后的HTML文件，批量替换TOC区域的MyBiz.CRM.Sales.为空字符串。但这种方法维护性差，后续docFX版本更新可能导致渲染结构变化，所以优先用原生方案。

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