头图

Docgeni 1.1.0 正式发布!

PingCode研发中心

本文由 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
  • 组件支持标签展示,默认包含newdeprecatedexperimental
  • 新增labelalertembed内置组件,通过 Markdown 扩展语法嵌入
  • 支持自定义内置组件,通过 Markdown 扩展语法嵌入
  • 文档底部显示 GitHub 的贡献者和最后更新时间
  • 文档底部展示上一篇和下一篇
  • 组件示例支持独立窗口打开

优化

  • 单元测试覆盖率提升至 85% 以上
  • 重构 CLI 日志和进度条,更友好的方式展示进度和构建结果
  • 文档目录激活位置计算优化
  • 文件变化后批量构建,提高构建性能
  • 支持在 URL 参数访问多语言 /zh-cn/xxx

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

自定义首页
简洁好看的首页和强大的自定义能力,让文档有个漂亮的门面。
image.png
配置首页和写普通文档一样,只需要加入herofeatures特殊的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 alertembed三种内置组件。
我们可以通过在 Markdown 中编写如下语法:

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

Label 和 Alert 内置组件的展示效果如下:
image.png

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 查找所有内置组件元素,比如 labelmy-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> 投影,顿时感觉太香了
image.png

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

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

  • toc: menu​表示在左侧的菜单中展示
  • toc: false | hidden​表示隐藏目录

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

组件支持标签
在我们编写组件库的时候,通过有些新增或者遗弃的组件需要在菜单中明显的标识一下,方便查阅。
image.png
只需要在对应的组件文档中编写label: new​ 这样的 FrontMatter 即可。此次提供了new​deprecatedexperimental​三种内置的标签,同时还提供了自定义标签和覆写原有标签的颜色和文案。只需要在对应的类库中配置 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​方法,当一次修改多个文件的时候会批量发送,只构建一次。
image.png

以上是 Docgeni 1.1.0​ 版本发布的所有内容,欢迎 Angular 用户关注和使用,你的使用和反馈是对开源最大的支持。
除了 Docgeni 外,我们还开源了多个 Angular 相关的项目,欢迎大家使用:

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

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

PingCode官网

关于PingCode

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

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

阅读 142
1 声望
3 粉丝
0 条评论
1 声望
3 粉丝
文章目录
宣传栏