本篇主要分享什么內(nèi)容：

• 常用的文檔/靜態(tài)站點(diǎn)生成工具有哪些
• 每個(gè)工具有什么特點(diǎn)
• 工具適應(yīng)場景

前置概念

• MarkDown
• MDX MarkDown + JSX
• YMAL Front Matter

組件庫文檔工具選型

AndD組件庫文檔是怎么制做的矾屯，使用了什么工具浮创。

以AntD Button組件為例，我們看一下antd組件庫的文檔頁面結(jié)構(gòu)構(gòu)成和文檔生成：

Button文檔

Button文檔倉庫源文件

網(wǎng)站文檔倉庫源文件

按鈕類型

bisheng

AntD使用了bisheng來生成組件庫文檔被啼，把MarkDown進(jìn)行拼接和渲染成最終的文檔展示頁面。

靜態(tài)站生成工具方案

1. vuePress

2. gitbook

3. MDX

   MarkDown + JSX

   支持導(dǎo)入React組件

   支持remark 生態(tài)系統(tǒng)中的任何插件

   Playground 實(shí)時(shí)修改棠枉，實(shí)時(shí)預(yù)覽

   基礎(chǔ)

   支持MarkDown語法

   完全支持JSX 以<字符開頭的行都視為JSX代碼塊

   支持import 和 exports

   import 組件 json數(shù)據(jù) md或mdx文檔

   MDXProvider

   提供MarkDown渲染HTML使用組件的映射 組件列表

4. Gatsby

   Demo

   1. 初始化

      npm init gatsby
      

      npm install -g gatsby-cli
      gatsby new
      

   2. 運(yùn)行

      npm run develop
      

   3. 特點(diǎn)：生態(tài)好浓体，功能豐富，有各種各樣的插件辈讶，支持MDX命浴。

      Gatsby 有一個(gè)強(qiáng)大的功能，稱為數(shù)據(jù)層贱除，使用 Gatsby 的數(shù)據(jù)層生闲，您可以組合來自多個(gè)來源的數(shù)據(jù)，這讓您可以為每種類型的數(shù)據(jù)選擇最佳平臺月幌。

      [圖片上傳失敗...(image-3176be-1649995078232)]

      http://localhost:8000/___graphql中可以看到GraphQL數(shù)據(jù)

   4. 數(shù)據(jù)來源
      Gatsby-source-*

      數(shù)據(jù)拉入：頁面數(shù)據(jù)拉入 使用頁面查詢碍讯，頁面中導(dǎo)出 query，通過graphql查詢即可

                    組件中拉入數(shù)據(jù)  可以使用useStaticQuery鉤子拉入扯躺，
      

   5. 動(dòng)態(tài)創(chuàng)建頁面

      Gatsby的 文件系統(tǒng)路由 API定義用于命名src/pages目錄中文件的特殊語法捉兴，它允許您根據(jù)數(shù)據(jù)層中的節(jié)點(diǎn)集合為站點(diǎn)動(dòng)態(tài)創(chuàng)建新頁面。

5. JSDoc

   根據(jù)javascript文件中注釋信息录语，生成JavaScript應(yīng)用程序或庫倍啥、模塊的API文檔 的工具

   安裝

   npm install -D jsdoc
   

   使用

   jsdoc  xxx.js
   

   默認(rèn)會輸出文檔到out文件夾，可以通過--destination指定輸出路徑

   jsdoc-to-markdown

6. TSDoc

   https://tsdoc.org/play

7. React Styleguidist

8. StoryBook

   一個(gè)強(qiáng)大的集組件開發(fā)澎埠，查看虽缕，測試的文檔工具，支持多種框架失暂。使用”組件驅(qū)動(dòng)開發(fā)“理念彼宠。

   • 支持多種框架 React Vue Angular Ember Preact Svelte等

   Tutorials

   CDD

9. docsify

   特點(diǎn)：

   • 簡單輕便
   • 沒有靜態(tài)構(gòu)建的 html 文件
   • 多個(gè)主題

   安裝

   npm i docsify-cli -g
   

   初始化

   docsify init ./docs
   

   預(yù)覽

   docsify serve docs
   

   目錄結(jié)構(gòu)

   index.html 文件入口

   README.md 主頁

   .nojekyll 防止GitHub Pages忽略以下劃線開頭的文件

   側(cè)邊欄

   創(chuàng)建 _sidebar.md（支持目錄層級嵌套）。

   _sidebar.md中頁面會自動(dòng)生成標(biāo)題和子標(biāo)題

   自定義導(dǎo)航欄

   • html標(biāo)簽
   • _navbar.md（同樣支持目錄層級嵌套弟塞，展示形式為彈窗）

   封面

   _coverpage.md #/ 首頁全屏展示

   可以指定背景圖和背景色

   可以指定只展示封面

   配置

   window.$docsify = {

   el:'#app', // 根元素

   repo:'docsifyjs/docsify/', //Git倉庫地址

   maxLevel: 6, // 目錄最大層級

   loadNavbar: false, // 加載_navbar.md作為導(dǎo)航欄(或者直接指定md路徑)

   loadSidebar: false, // 加載_sidebar.md作為側(cè)邊欄

   hideSidebar: true, // 隱藏側(cè)邊欄

   subMaxLevel: 0, // 在自定義側(cè)邊欄中添加目錄（最大層級）

   auto2top: true, // 頁面路徑改變時(shí)滾動(dòng)到屏幕頂部

   homepage: 'README.md', // #/ 主頁

   basePath: '/path/', // 基本路徑, 可以將其設(shè)置為其他目錄或其他域名

   relativePath: false, // 如果為 true凭峡，則鏈接是相對于當(dāng)前上下文的。

   coverpage: false, // 封面 默認(rèn)加載_coverpage.md决记，也可以指定md路徑

   logo,

   name,

   nameLink,

   markdown, // 自定義渲染MarkDown為HTML 文檔

   themeColor,

   executeScript: true,

   mergeNavbar: true, // 小屏幕上的導(dǎo)航欄將與側(cè)邊欄合并

   externalLinkTarget: '_self', // default: '_blank' 打開默認(rèn)連接方式

   routerMode: 'history', // default: 'hash' 路由模式

   onlyCover: false, // #/只展示封面

   requestHeaders: { 'x-token': 'xxx', }, // 設(shè)置請求資源頭

   notFoundPage: true, // 加載_404.md 或指定相應(yīng)的md

   vueComponents, // 注冊vue組件, 可在md中直接使用

   vueGlobalOptions,

   vueMounts

   }

   主題 官方和社區(qū)制作的主題

   插件 全文檢索摧冀，谷歌分析，表情符號，第三方腳本支持索昂，圖片縮放建车，在github上編輯，jsfiddler Demo預(yù)覽椒惨，復(fù)制到剪切板缤至，Gitalk, 分頁和標(biāo)簽等

   PWA

   SSR

   嵌入文件：支持視頻， 音頻康谆，iframe或代碼塊领斥，甚至MarkDown

10. Docz

    • 基于MDX進(jìn)行了封裝
    • 完全使用Gatsby構(gòu)建，可以使用Gatsby的插件和工具生態(tài)
    • 零配置
    • TypeScript支持

    安裝

    npm install docz # react react-dom
    

    運(yùn)行

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

    開發(fā)

    創(chuàng)建.mdx文件即可(指定name和route)沃暗。

    構(gòu)建

    npm run build # 生成靜態(tài)資源在.docz/dist目錄中
    npm run build -- --dest docs-site-directory  # 通過--dest 指定文檔生成目錄
    

    也可以在配置中指定打包輸出目錄

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

    部署

    構(gòu)建之后可以使用任何靜態(tài)站點(diǎn)托管服務(wù)進(jìn)行部署月洛。

    MDX支持

    可以直接引入.jsx/.tsx組件，樣式孽锥；

    內(nèi)置組件

    • Playground

      Playground支持編輯實(shí)時(shí)渲染嚼黔，支持函數(shù)組件和State

    • Props

      組件內(nèi)的prop-types定義和typeScript的Interface會通過<Props>轉(zhuǎn)換成表格展示

    文檔設(shè)置

    使用YMAL自定義文檔設(shè)置(也可以自定義屬性，用于自定義theme)

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

    CSS預(yù)處理器

    需要Gatsby提供的能力惜辑，安裝插件

    TypeScript支持

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

    如果需要精確控制組件后綴唬涧，可以使用filterComponents and docgenConfig進(jìn)行過濾

    支持自定義主題

    項(xiàng)目配置

    基本配置

    base 頁面訪問的basePath

    src 指定組件存放目錄

    files 指定docz解析文件查找路徑規(guī)則 默認(rèn)會查找所有擴(kuò)展名為.mdx的文件

    ignore 需要忽略解析的文件

    dest 指定docz build的目錄

    title Header展示title，默認(rèn)會去package.json中name字段

    description HTML中meta字段

    typescript typescript支持 默認(rèn)false .mdx文件中需要引入TypeScript組件則需要設(shè)置

    propsParser props格式化 供<Props />渲染使用韵丑，禁用可以提升性能爵卒。

    config 指定docz配置文件 默認(rèn)順序 docz.json | .doczrc | doczrc.json |doczrc.js | docz.config.js | docz.config.json

    public 指定公共目錄虚缎，絕對資源路徑會從這個(gè)目錄下取數(shù)據(jù)

    editBranch 點(diǎn)擊 Github 按鈕時(shí)用于編輯文檔的分支

    host devServer地址 默認(rèn) '127.0.0.1'

    port devServer 端口

    構(gòu)建流程

    menu 可指定菜單中文檔的順序

    plugins 指定要使用的插件數(shù)組

    組件和HooksAPI

    ComponentsProvider 將組件傳遞給 MDX撵彻，它們將在您將 Markdown 轉(zhuǎn)換為 html 時(shí)使用

    Playground 渲染組件并在其中顯示代碼的可編輯版本

    Props 獲取組件并根據(jù)組件中屬性定義生成屬性表的組件

    useComponents 配合ComponentsProvider使用

    useDocs 獲取所有已解析文檔的列表, 當(dāng)要?jiǎng)?chuàng)建菜單或列表之類的內(nèi)容時(shí)會很有用。

    useMenus 返回 Docz 構(gòu)建的菜單

    useConfig 獲取項(xiàng)目配置中項(xiàng)目配置對象

    支持自定義插件和MDX插件

    使用注意：每次涉及到路由的變化都需要重啟生效实牡，遇到緩存問題可以刪除.docz文件夾后重啟

    // 一個(gè)簡單的docz配置 doczrc.js
    export default {
      files: './docs/mdx/*.{md,markdown,mdx}',
      dest: './docs/site',
      title: 'Flex-Ctrip-Offline',
      typescript: true
    }
    

11. Dumi

    • 開箱即用
    • 為組件開發(fā)而生陌僵，支持Markdown擴(kuò)展，可以渲染組件
    • 主題系統(tǒng)创坞，支持自定義渲染樣式
    • API自動(dòng)生成碗短，基于TypeScript類型定義自動(dòng)生成組件API

    組件開發(fā)腳手架

    npx @umijs/create-dumi-lib   # 初始化一個(gè)文檔模式的組件庫開發(fā)腳手架
    npx @umijs/create-dumi-lib --site # 初始化一個(gè)站點(diǎn)模式的組件庫開發(fā)腳手架 (比文檔模式多一個(gè)主頁，主頁使用docs/index.md)
    # 也可手動(dòng)切換文檔模式 => 站點(diǎn)模式: 修改.umirc.ts,添加mode:'site'
    

    靜態(tài)站點(diǎn)腳手架

    npx @umijs/create-dumi-app
    

    運(yùn)行

    npm install 
    npm start
    

    構(gòu)建及部署

    npm run build
    

    目錄結(jié)構(gòu)

    ├── README.md
    ├── docs  # 組件庫文檔目錄
    │   ├── index.md # 組件庫文檔首頁(不存在會使用README.md)
    │   └── otherDir # 組件文檔其他路由
    │           ├── index.md
    │           ├── sample.md
    │           └── help.md
    ├── src   # 組件庫源碼目錄(單純文檔站點(diǎn)可忽略)
    │   ├── Foo
    │   └── index.ts
    ├── .umirc.ts # dumi配置文件
    └── .fatherrc.ts # father-build的配置文件用于組件庫打包
    

    代碼塊

    jsx和tsx的代碼塊會被dumi解析為React組件题涨，并進(jìn)行渲染偎谁。

    dumi引入組件原則：

    像用戶一樣使用組件：直接引入組件庫進(jìn)行文檔demo演示。不僅可以用來調(diào)試組件纲堵、編寫文檔巡雨，還能用來被用戶直接拷貝到項(xiàng)目中使用。dumi會為我們自動(dòng)創(chuàng)建組件庫NPM包->組件庫源代碼的映射席函。
    

    外部demo

    可以引入外部文件作為demo渲染铐望，并可支持查看demo源代碼

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

    直接嵌入渲染

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

    embed Markdow嵌套

    <!-- 引入全量的 Markdown 文件內(nèi)容 -->
    <embed src="/path/to/some.md"></embed>
    <!-- 根據(jù)行號引入指定行的 Markdown 文件內(nèi)容 -->
    <embed src="/path/to/some.md#L1"></embed>
    <!-- 根據(jù)行號引入部分 Markdown 文件內(nèi)容 -->
    <embed src="/path/to/some.md#L1-L10"></embed>
    <!-- 根據(jù)正則引入部分 Markdown 文件內(nèi)容 -->
    <embed src="/path/to/some.md#RE-/^[^\r\n]+/"></embed>
    

    組件API自動(dòng)生成

    JS Doc注釋 + TypeScript類型定義的方式實(shí)現(xiàn)組件API自動(dòng)生成

    如何在非-umi-項(xiàng)目中使用-dumi

    DEMO理念

目前我們選擇的是使用Docz來做為業(yè)務(wù)組件庫的文檔生成工具，下一篇會講一下我們?yōu)槭裁催x擇Docz,它有什么優(yōu)點(diǎn)。歡迎持續(xù)關(guān)注正蛙，微信公眾號”混沌前端“