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 中通过 <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落地研发管理。