微软文档生成工具 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,查看效果:

posted @ 2020-08-17 17:45  Watt不想上班  阅读(300)  评论(0编辑  收藏  举报