Docgeni 1.1.0 正式发布！工具敏捷开发优化进度条研发

本文由 Worktile 产品研发部负责人 @徐海峰分享
2021年的5月20日, Docgeni 正式对外宣布了开源，具体内容查看 Docgeni，开箱即用的 Angular 组件文档工具，时隔4个多月，Docgeni 也在慢慢的成长，为了喜迎国庆，今天终于等到了1.1.0版本的发布，那么接下来详细介绍一下1.1.0到底有哪些新的特性。
如果你还没有关注 Docgeni，可以去https://github.com/docgeni/do... 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: 10 hero: title: Docgeni description: 开箱即用的 Angular 组件文档生成工具 actions: - text: 快速上手 link: /guides/intro/getting-started btnShape: round - text: Design link: /guides/intro btnShape: square btnType: outline-primary-light features: - 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 中通过语法嵌入一个示例组件，其实这应该是最初的内置组件，那么本次 Docgeni 新增了 label 、alert和 embed三种内置组件。
我们可以通过在 Markdown 中编写如下语法：

Hello Docgeni Hello Docgeni

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

文章图片

embed 内置组件是在一个文档中嵌入另一个文档的内容，比如根目录已经有了一个 README.md，文档中想直接嵌入README.md文档的所有内容，复制一份涉及到之后修改需要同步两份，那么直接使用是最佳的方案，同时还可以指定嵌入某一行和行区间内容。关于内置组件更多的使用参考：内置组件。
自定义内置组件
除了提供默认的内置组件外，此次 Docgeni 还支持自定义内置组件，你可以使用 Angular 编写你自己想要的内置组件，然后在文档中嵌入使用。
比如：我要制定一个设置文字颜色的内置组件，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) { super(elementRef); } }export default { selector: 'my-color', component: MyColorComponent };

这样就可以在 Markdown 中编写 Color 实现设置文字颜色的效果了。
【Docgeni 1.1.0 正式发布！】Markdown 文档内容在 Docgeni 中是通过 marked 库解析成 HTML，然后内容区域通过设置 innerHTML 渲染出来的，那就意味着 Markdown 中的语法和 HTML 不会经过 Angular 编译，直接是原生的 DOM，但是我们编写的内置组件是 Angular 组件，那么如何解析并渲染 Angular 组件呢？

第一步：内容区域渲染完 HTML 后，通过注册的内置组件 selector 查找所有内置组件元素，比如 label、my-color等所有内置组件，contentElement.querySelectorAll("label")
第二步：查找到元素后，通过 Angular CDK 提供的DomPortalOutlet? 动态创建并渲染内置组件，然后替换掉原来的节点
第三步：获取 Markdown 语法中传入的参数和属性，比如?中的type? 和 class?，动态创建组件后通过赋值 type 和设置 Host 元素的 Attribute 传递到子组件中

为了让每个内置组件不用重复的提供设置属性的方法，基类 DocgeniBuiltInComponent? 提供了统一的 setAttribute?方法。
其中遇到了连个技术难点：
Angular CDK DomPortalOutlet?渲染 DOM会保留原有的节点，在原有节点下方渲染新的组件，这样就导致生成的 HTML 中有多个元素，不整洁，解决办法就是自定义了一个 DomPortalOutlet?把appendChild 换成了 replaceWith?CDK 暂时不提供自定义的扩展能力
在 Markdown 中编写的语法，content 内容投影如何投影到 Angular 内置组件中，起初我的设计是在内置组件中编写一个 ? 然后在渲染后动态替换，后来发现 Angular 在动态创建组件的第四个参数 projectableNodes?就是替换组件中的投影，顿时感觉太香了

文章图片

文档目录(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落地研发管理。