前言

在我們開發(fā)完一個組件庫的時候蒋搜，需要有一個組件說明文檔胰伍，文檔頁面是最直接的獲取信息的窗口骂租。而文檔頁一般包含了這些信息：

• 組件的描述
• 組件 Demo 示例的展示渗饮、描述和源碼
• 組件的參數(shù)文檔

組件說明文檔是讓其他人了解組件庫的關鍵環(huán)節(jié)互站，包括組件庫的適用范圍（pc端胡桃，移動端翠胰，輕量級還是重量級）自脯，兼容瀏覽器的版本膏潮，設計原則和背景焕参，以及社區(qū)生態(tài)，使用方法等桐磁。

關于如何開發(fā)組件庫我擂，可看這篇：

heaven-ui

文檔生成

這里推薦 vuepress 缓艳，可以快速幫我們完成組件庫文檔的建設阶淘。(https://vuepress.vuejs.org/zh/guide/)

vuepress是一個文檔生成工具，默認的樣式和vue官方文檔幾乎是一致的坤塞，因為創(chuàng)造它的初衷就是想為vue和相關的子項目提供文檔支持灼狰。它內(nèi)置了 Markdown的擴展浮禾，寫文檔的時候就是用 markdown來寫盈电，最讓人省心的是你可以直接在 Markdown 文件中使用Vue組件匆帚，意味著我們的組件庫中寫的一個個組件吸重，可以直接放到文檔里去用晤锹，展示組件的實際運行效果鞭铆。 我的案例網(wǎng)站也就是通過vuepress來寫的车遂，生成靜態(tài)網(wǎng)站后舶担，用 gh-pages 直接部署到github上衣陶，也可以直接部署到我們自己的網(wǎng)站上剪况。

vuepress更好的一點在于你可以自定義其webpack配置和主題译断，意味著你可以讓你自己的文檔站點在開發(fā)階段有更多的功能特性的支持或悲，同時可以把站點風格改成自己的一套主題風格。這就無需我們重頭開始去做一套了淮菠，對于咱們想要快速完成組件庫文檔建設這一需求來說杨蛋，還是挺有效的曙寡。

img

VuePress搭建文檔

VuePress 是 Vue 驅動的靜態(tài)網(wǎng)站生成器举庶。支持在 Markdown 中使用 Vue 組件户侥，簡潔蕊唐，高性能。當然你也可以使用其他的文檔生成器烁设，如 Docz替梨、Storybook 等。

可以根據(jù)官方文檔學習如何使用：https://www.vuepress.cn/guide/getting-started.html

項目生成及配置

安裝

可以右鍵手動新建装黑，也可以使用 mkdir 命令新建：

mkdir heavenUi && cd heavenUi

全局安裝VuePress

npm install -g vuepress

進入 vuepressBlogDemo 文件夾副瀑，初始化項目

使用 npm init 或 npm init -y（默認yes）

npm init -y

配置scripts

package.json

{ 
     "docs:dev": "vuepress dev docs", 
     "docs:build": "vuepress build docs" 
}

初始化docs

創(chuàng)建目錄和文件如下圖所示

VuePress 遵循 “約定優(yōu)于配置” 的原則，推薦的目錄結構如下：

.
├── docs
│   ├── .vuepress (可選的)
│   │   ├── components (可選的)
│   │   ├── theme (可選的)
│   │   │   └── Layout.vue
│   │   ├── public (可選的)
│   │   ├── styles (可選的)
│   │   │   ├── index.styl
│   │   │   └── palette.styl
│   │   ├── templates (可選的, 謹慎配置)
│   │   │   ├── dev.html
│   │   │   └── ssr.html
│   │   ├── config.js (可選的)
│   │   └── enhanceApp.js (可選的)
│   │ 
│   ├── README.md
│   ├── guide
│   │   └── README.md
│   └── config.md
│ 
└── package.json

注意

請留意目錄名的大寫恋谭。

• docs/.vuepress: 用于存放全局的配置糠睡、組件、靜態(tài)資源等疚颊。

1. docs/.vuepress/components: 該目錄中的 Vue 組件將會被自動注冊為全局組件狈孔。
2. docs/.vuepress/theme: 用于存放本地主題均抽。
3. docs/.vuepress/styles: 用于存放樣式相關的文件。
4. docs/.vuepress/styles/index.styl: 將會被自動應用的全局樣式文件，會生成在最終的 CSS 文件結尾持灰，具有比默認樣式更高的優(yōu)先級妥泉。
5. docs/.vuepress/styles/palette.styl: 用于重寫默認顏色常量刽沾，或者設置新的 stylus 顏色常量监氢。
6. docs/.vuepress/public: 靜態(tài)資源目錄纺弊。
7. docs/.vuepress/templates: 存儲 HTML 模板文件。
8. docs/.vuepress/templates/dev.html: 用于開發(fā)環(huán)境的 HTML 模板文件腊脱。
9. docs/.vuepress/templates/ssr.html: 構建時基于 Vue SSR 的 HTML 模板文件。
10. docs/.vuepress/config.js: 配置文件的入口文件，也可以是 YML 或 toml。
11. docs/.vuepress/enhanceApp.js: 客戶端應用的增強寸痢。

首頁信息設置

---
home: true
actionText: 開始使用
# 網(wǎng)站入口 根據(jù)自己的首頁配置路徑
actionLink: /component/installation
features:
- title: heaven-UI
  details: 一套基于 Vue.js 的高質量UI 組件庫
footer: MIT Licensed | COPYRIGHT ?
---

首頁效果如下

img

配置導航

module.exports = {
  title: 'Heaven', // 設置網(wǎng)站標題
  description: '輕量憔辫、可靠的 Vue 組件庫', // 描述
  dest: './dist', // 設置輸出目錄
  themeConfig: { // 主題配置
    nav: [ // 頭部導航條
      {
        text: '主頁',
        link: '/'
      },
      {
        text: "組件",
        link: "/component/installation",
      },
    ],
    // 為以下路由添加側邊欄
    sidebar: {
      '/components/': [
        {
          title: '組件',
          collapsable: false,
          children: [
            'button',
            // ... 其他組件
          ]  
        },
        // 其他設置
      ]
    }
  }
}

客戶端應用的增強文件

enhanceApp.js

這個文件用于添加組件Demo展示的優(yōu)化的配置

安裝

npm install heaven-ui less less-loader --save

如需本地調試令境，可link開發(fā)的組件庫 heaven-ui

npm link heaven-ui

.vuepress/enhanceApp.js

/**
 * 擴展 VuePress 應用
 */
import Heaven from 'heaven-ui'
import 'heaven-ui/lib/heaven-ui.min.css'
 
export default ({
 Vue, // VuePress 正在使用的 Vue 構造函數(shù)
 options, // 附加到根實例的一些選項
 router, // 當前應用的路由實例
 siteData // 站點元數(shù)據(jù)
}) => {
 // ...做一些其他的應用級別的優(yōu)化
 Vue.use(Heaven)
}

.vuepress/components/button.vue文件可以進行button組件的Demo展示的樣式

在md文件內(nèi)增加<ClientOnly></ClientOnly> 就可直接渲染button.vue的內(nèi)容

<template>
  <div>
    <h-button>默認按鈕</h-button>
    <h-button type="primary">主要按鈕</h-button>
    <h-button type="success">成功按鈕</h-button>
    <h-button type="warning">警告按鈕</h-button>
    <h-button type="danger">危險按鈕</h-button>
    <h-button type="info">信息按鈕</h-button>   
  </div>
</template>

<script>
export default {
}
</script>

<style>
</style>

編寫對應組件的Markdown文件

#### Button 按鈕

#### 常用的操作按鈕弥鹦。
<ClientOnly>
<button></button>
</ClientOnly>

``` html
<template>
   <h-button>默認按鈕</h-button>
   <h-button type="primary">主要按鈕</h-button>
   <h-button type="success">成功按鈕</h-button>
   <h-button type="warning">警告按鈕</h-button>
   <h-button type="danger">危險按鈕</h-button>
   <h-button type="info">信息按鈕</h-button>
</template>
```

效果如下

img

訪問 http://localhost:8080 即可看到文檔了。當然油湖，可以將文檔部署到自己的服務器胧瓜，也可以部署到 Github pages 上蘑拯。

小結

至此，組件庫的說明文檔就搭建完成恩脂，后續(xù)自行補充文檔即可。

組件庫地址

倉庫地址

文檔演示地址