Docgeni 1.1.0 正式发布！

本文由 Worktile 产品研发部负责人 @徐海峰 分享

2021 年的 5 月 20 日, Docgeni 正式对外宣布了开源，具体内容查看 Docgeni，开箱即用的 Angular 组件文档工具，时隔 4 个多月，Docgeni 也在慢慢的成长，为了喜迎国庆，今天终于等到了1.1.0​​ 版本的发布，那么接下来详细介绍一下1.1.0​到底有哪些新的特性。

如果你还没有关注 Docgeni，可以去 https://github.com/docgeni/docgeni Star 一下。

官网地址：https://docgeni.org

1.1.0 更新盘点

新特性

• full​模式下的自定义首页功能

• 自定义footer​功能

• 文档目录(toc)支持多种展现形式（content | menu | hidden​）

• 组件支持标签展示，默认包含new​、deprecated和experimental
  

• 新增label​、alert​ 和embed​内置组件，通过 Markdown 扩展语法嵌入

• 支持自定义内置组件，通过 Markdown 扩展语法嵌入

• 文档底部显示 GitHub 的贡献者和最后更新时间

• 文档底部展示上一篇和下一篇

• 组件示例支持独立窗口打开

优化

• 单元测试覆盖率提升至 85% 以上

• 重构 CLI 日志和进度条，更友好的方式展示进度和构建结果

• 文档目录激活位置计算优化

• 文件变化后批量构建，提高构建性能

• 支持在 URL 参数访问多语言 /zh-cn/xxx​
  



那么接下来简单挑几个有代表性的特性详细介绍一下：

自定义首页

简洁好看的首页和强大的自定义能力，让文档有个漂亮的门面。



配置首页和写普通文档一样，只需要加入 hero​和 features​特殊的 FrontMatter​ 即可，详情配置查看官网的 自定义首页 了解更多。

---title: 首页order: 10hero:  title: Docgeni  description: 开箱即用的 Angular 组件文档生成工具  actions:    - text: 快速上手      link: /guides/intro/getting-started      btnShape: round    - text: Design      link: /guides/intro      btnShape: square      btnType: outline-primary-lightfeatures:  - icon: https://cdn.pingcode.com/open-sources/docgeni/home/feature1.png    title: 开箱即用    description: 根据目录结构自动生成导航和菜单，同时通过命令行工具帮助开发者零成本上手，让你快速开始文档编写和组件开发  - icon: https://cdn.pingcode.com/open-sources/docgeni/home/feature2.png    title: 为 Angular 组件开发而生    description: 独立的 Angular 组件预览体验，组件概览，示例，API，丰富的 Markdown 扩展，使文档编写起来更简单，支持同时存在多个类库   - icon: https://cdn.pingcode.com/open-sources/docgeni/home/feature3.png    title: 两种模式和多种风格支持    description: 支持 full 和 lite 两种模式满足不同的需求，同时支持默认和 Angular 风格，让用户选择适合自己的主题  - icon: https://cdn.pingcode.com/open-sources/docgeni/home/feature4.png    title: 强大的自定义能力    description: 提供了 publicDir 实现自定义 HTML，资源，样式等功能，同时支持完全自定义的站点  - icon: https://cdn.pingcode.com/open-sources/docgeni/home/feature5.png    title: 组件 API 自动生成（暂时未支持）    description: 基于 TypeScript 类型定义和注释自动生成组件 API，维护代码和文档始终如一  - icon: https://cdn.pingcode.com/open-sources/docgeni/home/feature6.png    title: 多语言支持    description: 支持灵活的多语言配置---

内置组件

之前我们可以通过在 Markdown 中通过 <example name="xxx" inline />​ 语法嵌入一个示例组件，其实这应该是最初的内置组件，那么本次 Docgeni 新增了 label​ 、alert​ ​和 embed​ 三种内置组件。

我们可以通过在 Markdown 中编写如下语法：

<label>Hello Docgeni</label><alert>Hello Docgeni</alert><embed src="./foo.md"></embed>

Label 和 Alert 内置组件的展示效果如下：



embed 内置组件是在一个文档中嵌入另一个文档的内容，比如根目录已经有了一个 README.md​，文档中想直接嵌入README.md​文档的所有内容，复制一份涉及到之后修改需要同步两份，那么直接使用 <embed src="./README.md"></embed>​ 是最佳的方案，同时还可以指定嵌入某一行和行区间内容。关于内置组件更多的使用参考：内置组件 。

自定义内置组件

除了提供默认的内置组件外，此次 Docgeni 还支持自定义内置组件，你可以使用 Angular 编写你自己想要的内置组件，然后在文档中嵌入使用。

比如：我要制定一个设置文字颜色的内置组件，<my-color color="red">Color</my-color>​

那么只需要在 .docgeni/components​ 默认文件夹中新建 color 组件，继承 DocgeniBuiltInComponent​ 基类，默认导出 selector 和 component 即可，此处的 selector 为 Markdown 中的标签语法，非 Angular 组件的选择器。

import { Component, ElementRef, HostBinding, Input, OnInit } from '@angular/core';import { DocgeniBuiltInComponent } from '@docgeni/template';
@Component({    selector: 'my-color',    templateUrl: './color.component.html'})export class MyColorComponent extends DocgeniBuiltInComponent implements OnInit {    @Input() set color(value: string) {        this.hostElement.style.color = value;    }
    constructor(elementRef: ElementRef<unknown>) {        super(elementRef);    }}
export default {    selector: 'my-color',    component: MyColorComponent};

这样就可以在 Markdown 中编写 <my-color color="red">Color</my-color>​ 实现设置文字颜色的效果了。

Markdown 文档内容在 Docgeni 中是通过 marked 库解析成 HTML，然后内容区域通过设置 innerHTML​ 渲染出来的，那就意味着 Markdown 中的语法和 HTML 不会经过 Angular 编译，直接是原生的 DOM，但是我们编写的内置组件是 Angular 组件，那么如何解析并渲染 Angular 组件呢？

• 第一步：内容区域渲染完 HTML 后，通过注册的内置组件 selector​ 查找所有内置组件元素，比如 label​、my-color​等所有内置组件，contentElement.querySelectorAll("label")​
  

• 第二步：查找到元素后，通过 Angular CDK 提供的DomPortalOutlet​ 动态创建并渲染内置组件，然后替换掉原来的节点

• 第三步：获取 Markdown 语法中传入的参数和属性，比如<label type="primary" class="label"></label>​中的type​ 和 class​，动态创建组件后通过赋值 type 和设置 Host 元素的 Attribute 传递到子组件中

为了让每个内置组件不用重复的提供设置属性的方法，基类 DocgeniBuiltInComponent​ 提供了统一的 setAttribute​方法。

其中遇到了连个技术难点：

• Angular CDK DomPortalOutlet​渲染 DOM 会保留原有的节点，在原有节点下方渲染新的组件，这样就导致生成的 HTML 中有多个元素，不整洁，解决办法就是自定义了一个 DomPortalOutlet​把appendChild 换成了 replaceWith​CDK 暂时不提供自定义的扩展能力

• 在 Markdown 中编写的语法，content 内容投影如何投影到 Angular 内置组件中，起初我的设计是在内置组件中编写一个 <div id="dg-content"></div>​ 然后在渲染后动态替换，后来发现 Angular 在动态创建组件的第四个参数 projectableNodes​就是替换组件中的 <ng-content> 投影，顿时感觉太香了

文档目录(toc)支持多种展现形式

默认情况下，Docgeni 会动态的获取页面所有标题（heading），生成树形目录并在文档右侧展示，这次新增了文档的 toc FrontMatter 配置多种展现形式

• toc: content​ 表示在文档右侧展示，也就是默认的模式

• toc: menu​表示在左侧的菜单中展示

• toc: false | hidden​表示隐藏目录

同时 全局配置 toc 是配置所有文档默认的目录展现形式，如果所有的文档你都想隐藏或者在左侧菜单显示，可以配置为menu​或者false​ 。





组件支持标签

在我们编写组件库的时候，通过有些新增或者遗弃的组件需要在菜单中明显的标识一下，方便查阅。



只需要在对应的组件文档中编写label: new​ 这样的 FrontMatter 即可。此次提供了new​、deprecated和experimental​三种内置的标签，同时还提供了自定义标签和覆写原有标签的颜色和文案。只需要在对应的类库中配置 labels 即可，配置如下：



labels: {  "new": { "text": "New", "color": "#73D897" },  "deprecated": { "text": "Deprecated", "color": "#AAAAAA" },  "experimental": { "text": "Experimental", "color": "#F6C659" }}

详细说明参考：类库配置 -> labels

更友好的进度展示

此次更新还优化了 CLI 的进度和日志展示，为了支持第一次和增量构建的进度和日志展示，底层代码进行了一次重构，采用了类似 Webpack 的 Compilation​ 机制，每次构建创建一个新的 Compilation​，同时日志和进度都是通过 Compilation​提供的 hooks 事件打印和展示的，底层也提供了 watchAggregated​方法，当一次修改多个文件的时候会批量发送，只构建一次。





以上是 Docgeni 1.1.0​ 版本发布的所有内容，欢迎 Angular 用户关注和使用，你的使用和反馈是对开源最大的支持。

除了 Docgeni 外，我们还开源了多个 Angular 相关的项目，欢迎大家使用：

• ngx-planet Angular 框架开箱即用的微前端框架

• slate-angular slate 编辑器框架的 Angular 视图层

• ngx-gantt 最好用且强大的 Angular 甘特图组件

同时也维护了 ngnice 站点，最近翻译了 RxJS 指栏相关文档 https://ngnice.com/rxjs/into ，需要的可以查看。

最后，推荐我们的智能化研发管理工具 PingCode 给大家。

PingCode

关于 PingCode

PingCode 是由国内老牌 SaaS 厂商 Worktile 打造的智能化研发管理工具，围绕企业研发管理需求推出了 Agile（敏捷开发）、Testhub（测试管理）、Wiki（知识库）、Plan（项目集）、Goals（目标管理）、Flow（自动化管理）、Access （目录管理）七大子产品以及应用市场，实现了对项目、任务、需求、缺陷、迭代规划、测试、目标管理等研发管理全流程的覆盖以及代码托管工具、CI/CD 流水线、自动化测试等众多主流开发工具的打通。

自正式发布以来，以酷狗音乐、商汤科技、电银信息、51 社保、万国数据、金鹰卡通、用友、国汽智控、智齿客服、易快报等知名企业为代表，已经有超过 13 个行业的众多企业选择 PingCode 落地研发管理。