关于工具:Docgeni-110-正式发布

7次阅读

共计 5258 个字符，预计需要花费 14 分钟才能阅读完成。

本文由 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 换成了 replaceWithCDK 临时不提供自定义的扩大能力
在 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 落地研发治理。

正文完