乐趣区

关于javascript:前端组件库文档解决方案

jiezi

本篇次要分享什么内容：

  • 罕用的文档 / 动态站点生成工具有哪些
  • 每个工具有什么特点
  • 工具适应场景

前置概念

  • MarkDown
  • MDX MarkDown + JSX
  • YMAL Front Matter

组件库文档工具选型

AndD 组件库文档是怎么制做的，应用了什么工具。

以 AntD Button 组件为例，咱们看一下 antd 组件库的文档页面构造形成和文档生成：

Button 文档

Button 文档仓库源文件

网站文档仓库源文件

按钮类型

bisheng

AntD 应用了 bisheng 来生成组件库文档，把 MarkDown 进行拼接和渲染成最终的文档展现页面。

动态站生成工具计划

  1. vuePress
  2. gitbook

  3. MDX

    MarkDown + JSX

    反对导入 React 组件

    反对 remark 生态系统中的任何插件

    Playground 实时批改，实时预览

    根底

    反对 MarkDown 语法

    齐全反对 JSX 以 < 字符结尾的行都视为 JSX 代码块

    反对 import 和 exports

    import 组件 json 数据 md 或 mdx 文档

    MDXProvider

    提供 MarkDown 渲染 HTML 应用组件的映射 组件列表

  1. Gatsby

    Demo

    1. 初始化

      npm init gatsby
      npm install -g gatsby-cli
gatsby new

    2. 运行

      npm run develop

    3. 特点：生态好，功能丰富，有各种各样的插件，反对 MDX。

      Gatsby 有一个弱小的性能，称为 数据层，应用 Gatsby 的数据层，您能够组合来自多个起源的数据，这让您能够为每种类型的数据抉择最佳平台。

      http://localhost:8000/___graphql 中能够看到 GraphQL 数据

    4. 数据起源
      Gatsby-source-*

      数据拉入：页面数据拉入 应用页面查问，页面中导出 query，通过 graphql 查问即可

      ​ 组件中拉入数据 能够应用 useStaticQuery 钩子拉入，

    5. 动态创建页面

      Gatsby 的 文件系统路由 API 定义用于命名 src/pages 目录中文件的非凡语法，它容许您依据数据层中的节点 汇合 为站点动态创建新页面。

  1. JSDoc

    依据 javascript 文件中正文信息，生成 JavaScript 应用程序或库、模块的 API 文档 的工具

    装置

    npm install -D jsdoc

    应用

    jsdoc  xxx.js

    默认会输入文档到 out 文件夹，能够通过 --destination 指定输入门路

    jsdoc-to-markdown

  1. TSDoc

    https://tsdoc.org/play

  1. React Styleguidist

  1. StoryBook

    ​ 一个弱小的集组件开发，查看，测试的文档工具，反对多种框架。应用”组件驱动开发“理念。

    - 反对多种框架 React Vue Angular Ember Preact Svelte 等

    Tutorials

    CDD

  1. docsify

    特点：

    • 简略轻便
    • 没有动态构建的 html 文件
    • 多个主题

    装置

    npm i docsify-cli -g

    初始化

    docsify init ./docs

    预览

    docsify serve docs

    目录构造

    index.html 文件入口

    README.md 主页

    .nojekyll 避免 GitHub Pages 疏忽以下划线结尾的文件

    侧边栏

    创立 _sidebar.md（反对目录层级嵌套）。

    _sidebar.md 中页面会主动生成题目和子标题

    自定义导航栏

    • html 标签
    • _navbar.md（同样反对目录层级嵌套，展现模式为弹窗）

    封面

    _coverpage.md #/ 首页全屏展现

    能够指定背景图和背景色

    能够指定只展现封面

    配置

    window.$docsify = {

    ​ el:’#app’, // 根元素

    ​ repo:’docsifyjs/docsify/’, //Git 仓库地址

    ​ maxLevel: 6, // 目录最大层级

    ​ loadNavbar: false, // 加载_navbar.md 作为导航栏(或者间接指定 md 门路)

    ​ loadSidebar: false, // 加载_sidebar.md 作为侧边栏

    ​ hideSidebar: true, // 暗藏侧边栏

    ​ subMaxLevel: 0, // 在自定义侧边栏中增加目录（最大层级）

    ​ auto2top: true, // 页面门路扭转时滚动到屏幕顶部

    ​ homepage: ‘README.md’, // #/ 主页

    ​ basePath: ‘/path/’, // 根本门路, 能够将其设置为其余目录或其余域名

    ​ relativePath: false, // 如果为 true，则链接是绝对于以后上下文的。

    ​ coverpage: false, // 封面 默认加载_coverpage.md，也能够指定 md 门路

    ​ logo,

    ​ name,

    ​ nameLink,

    ​ markdown, // 自定义渲染 MarkDown 为 HTML 文档

    ​ themeColor,

    ​ executeScript: true,

    ​ mergeNavbar: true, // 小屏幕上的导航栏将与侧边栏合并

    ​ externalLinkTarget: ‘_self’, // default: ‘_blank’ 关上默认连贯形式

    ​ routerMode: ‘history’, // default: ‘hash’ 路由模式

    ​ onlyCover: false, // #/只展现封面

    ​ requestHeaders: {‘x-token’: ‘xxx’,}, // 设置申请资源头

    ​ notFoundPage: true, // 加载_404.md 或指定相应的 md

    ​ vueComponents, // 注册 vue 组件, 可在 md 中间接应用

    ​ vueGlobalOptions,

    ​ vueMounts

    }

    主题 官网和社区制作的主题

    插件 全文检索，谷歌剖析，表情符号，第三方脚本反对，图片缩放，在 github 上编辑，jsfiddler Demo 预览，复制到剪切板，Gitalk, 分页和标签等

    PWA

    SSR

    嵌入文件：反对视频，音频，iframe 或代码块，甚至 MarkDown

  1. Docz

    • 基于 MDX 进行了封装
    • 齐全应用 Gatsby 构建，能够应用 Gatsby 的插件和工具生态
    • 零配置
    • TypeScript 反对

    装置

    npm install docz # react react-dom

    运行

    "scripts": {
    "docz:dev": "docz dev",
    "docz:build": "docz build",
    "docz:serve": "docz build && docz serve"
}

    开发

    创立.mdx 文件即可(指定 name 和 route)。

    构建

    npm run build # 生成动态资源在.docz/dist 目录中
npm run build -- --dest docs-site-directory  # 通过 --dest 指定文档生成目录

    也能够在配置中指定打包输入目录

    // doczrc.js
export default {dest: '/some-folder'}

    部署

    构建之后能够应用任何动态站点托管服务进行部署。

    MDX 反对

    能够间接引入.jsx/.tsx 组件，款式；

    内置组件

    • Playground

      Playground 反对编辑实时渲染，反对函数组件和 State

    • Props

      组件内的 prop-types 定义和 typeScript 的 Interface 会通过 <Props> 转换成表格展现

    文档设置

    应用 YMAL 自定义文档设置(也能够自定义属性，用于自定义 theme)

    ---
name: My Document
route: /custom-route
menu: Documents
hidden: false
---

    CSS 预处理器

    须要 Gatsby 提供的能力，装置插件

    TypeScript 反对

    // doczrc.js
export default {typescript: true}

    如果须要准确管制组件后缀，能够应用 filterComponents and docgenConfig 进行过滤

    反对自定义主题

    我的项目配置

    根本配置

    base 页面拜访的 basePath

    src 指定组件寄存目录

    files 指定 docz 解析文件查找门路规定 默认会查找所有扩大名为.mdx 的文件

    ignore 须要疏忽解析的文件

    dest 指定 docz build 的目录

    title Header 展现 title，默认会去 package.json 中 name 字段

    description HTML 中 meta 字段

    typescript typescript 反对 默认 false .mdx 文件中须要引入 TypeScript 组件则须要设置

    propsParser props 格式化 供 <Props /> 渲染应用，禁用能够晋升性能。

    config 指定 docz 配置文件 默认程序 docz.json | .doczrc | doczrc.json |doczrc.js | docz.config.js | docz.config.json

    public 指定公共目录，相对资源门路会从这个目录下取数据

    editBranch 点击 Github 按钮时用于编辑文档的分支

    host devServer 地址 默认 ‘127.0.0.1’

    port devServer 端口

    构建流程

    menu 可指定菜单中文档的程序

    plugins 指定要应用的插件数组

    组件和 HooksAPI

    ComponentsProvider 将组件传递给 MDX，它们将在您将 Markdown 转换为 html 时应用

    Playground 渲染组件并在其中显示代码的可编辑版本

    Props 获取组件并依据组件中属性定义生成属性表的组件

    useComponents 配合 ComponentsProvider 应用

    useDocs 获取所有已解析文档的列表, 当要创立菜单或列表之类的内容时会很有用。

    useMenus 返回 Docz 构建的菜单

    useConfig 获取我的项目配置中我的项目配置对象

    反对自定义插件和 MDX 插件

    应用留神：每次波及到路由的变动都须要重启失效，遇到缓存问题能够删除.docz 文件夹后重启

    // 一个简略的 docz 配置 doczrc.js
export default {files: './docs/mdx/*.{md,markdown,mdx}',
  dest: './docs/site',
  title: 'Flex-Ctrip-Offline',
  typescript: true
}

  1. Dumi

    • 开箱即用
    • 为组件开发而生，反对 Markdown 扩大，能够渲染组件
    • 主题零碎，反对自定义渲染款式
    • API 主动生成，基于 TypeScript 类型定义主动生成组件 API

    组件开发脚手架

    npx @umijs/create-dumi-lib   # 初始化一个文档模式的组件库开发脚手架
npx @umijs/create-dumi-lib --site # 初始化一个站点模式的组件库开发脚手架 (比文档模式多一个主页，主页应用 docs/index.md)
# 也可手动切换文档模式 => 站点模式: 批改.umirc.ts, 增加 mode:'site'

    动态站点脚手架

    npx @umijs/create-dumi-app

    运行

    npm install 
npm start

    构建及部署

    npm run build

    目录构造

    ├── README.md
├── docs  # 组件库文档目录
│   ├── index.md # 组件库文档首页(不存在会应用 README.md)
│   └── otherDir # 组件文档其余路由
│           ├── index.md
│           ├── sample.md
│           └── help.md
├── src   # 组件库源码目录(单纯文档站点可疏忽)
│   ├── Foo
│   └── index.ts
├── .umirc.ts # dumi 配置文件
└── .fatherrc.ts # father-build 的配置文件用于组件库打包

    代码块

    jsx 和 tsx 的代码块会被 dumi 解析为 React 组件，并进行渲染。

    dumi 引入组件准则：

    ​ 像用户一样应用组件：间接引入组件库进行文档 demo 演示。不仅能够用来调试组件、编写文档，还能用来被用户间接拷贝到我的项目中应用。dumi 会为咱们主动创立组件库 NPM 包 -> 组件库源代码的映射。

    内部 demo

    能够引入内部文件作为 demo 渲染，并可反对查看 demo 源代码

    <code src="/path/to/complex-demo.tsx"></code>

    间接嵌入渲染

    ```jsx
/**
 * inline: true
 */
import React from 'react';
export default () => '我会被间接嵌入';
```

    embed Markdow 嵌套

    <!-- 引入全量的 Markdown 文件内容 -->
<embed src="/path/to/some.md"></embed>
<!-- 依据行号引入指定行的 Markdown 文件内容 -->
<embed src="/path/to/some.md#L1"></embed>
<!-- 依据行号引入局部 Markdown 文件内容 -->
<embed src="/path/to/some.md#L1-L10"></embed>
<!-- 依据正则引入局部 Markdown 文件内容 -->
<embed src="/path/to/some.md#RE-/^[^\r\n]+/"></embed>

    组件 API 主动生成

    JS Doc 正文 + TypeScript 类型定义的形式实现组件 API 主动生成

    如何在非 -umi- 我的项目中应用 -dumi

    DEMO 理念

目前咱们抉择的是应用 Docz 来做为业务组件库的文档生成工具，下一篇会讲一下咱们为什么抉择 Docz, 它有什么长处。欢送继续关注，微信公众号”混沌前端“

退出移动版