微软文档生成工具 docfx 学习笔记（二）

参考链接：

DocFX - static documentation generator | DocFX website

一、侧边栏使用二级菜单

在侧边栏使用二级菜单使菜单的内容分组，更加清晰明了。效果如图。

首先，明确一下，菜单的生成原理。菜单/导航，分为两个部分，顶部的导航栏，和页面的左边的侧边栏。导航栏上的链接对应的是项目根目录下的 toc.yml 。name 为链接显示的名称，href 为链接的url。因为 DocFX 最后生成的是一个静态的网站，所以文件夹名称也会被映射为 url 路径的一部分。

- name: Articles
  href: fusion/
- name: Api Documentation
  href: api/

链接若为 fusion/ 形式，fusion为一个文件夹，文件夹内可能对应多个文件或者还有文件夹。再通过 fusion 文件夹下的 toc 映射的文件与url 关系查找路径。

以下通过一个例子举例来说明如何创建二级菜单。

新建一个 articles2 文件夹，结构如下：

文件夹内新建一个 userguide.md 和 toc.yml，toc.yml 设置内容如下：

- name: UserGuide
  href: userguide.md

新建一个 fusion 文件夹，结构如下：

fusion 文件夹内新建一个 toc.yml，里面分别添加指向到 articles 和 articles2 文件夹内 toc.yml 文件的链接映射关系，如下所示：

- name: Articles
  href: ../articles/toc.yml
- name: Guides
  href: ../articles2/toc.yml

根目录下 toc.yml 修改，将 Articles 的地址修改 如下所示：

- name: Articles
  href: fusion/
- name: Api Documentation
  href: api/

再将fusion文件夹和articles2文件夹配置到docfx.json中的内容中，如下所示：

构建 Website，运行看下效果。

二、排除不想要的部分

默认情况下，DocFX 会生成所有代码的元数据，如果有些没有必要的部分就不需要生成，比如下图的 LittleBlog.Web 和 LittleBlog.Web.Areas.Identity 两个命名空间就是不需要的，需要排除掉，需要添加排除设置。

添加排除配置文件filterConfig.yml，增加如下内容：

apiRules:
- exclude:
    uidRegex: ^LittleBlog\.Web$
    type: Namespace
- exclude:
    uidRegex: ^LittleBlog\.Web\.Areas\.Identity$
    type: Namespace

以上内容排除了 LittleBlog.Web 和 LittleBlog.Web.Areas.Identity 两个 Namespace。规则名称 apiRules 有命名要求，大概是 docfx.json 中 metadata 的 dest + "Rules"，否则不会生效。

修改根目录下的 docfx.json，添加过滤配置文件的配置，如下所示：

"metadata": [
    {
      "src": [
        {
          "src": "../../LittleBlog/",
          "files": [
            "**.sln"
          ],
          "exclude": [
            "**/bin/**",
            "**/obj/**",
            "_site/**"
          ]
        }
      ],
      "dest": "api",
      "disableGitFeatures": false,
      "disableDefaultFilter": false,
+     "filter": "filterConfig.yml"
    }

重新构建 Website，查看效果：