Vitepress搭建組件庫文檔（上）—— 基本配置

2022 年 10 月 25 日
筆記
vite, VUE, 前端, 組件庫

在 vite 出現以前，vuepress 是搭建組件庫文檔不錯的工具，支援以 Markdown 方式編寫文檔。伴隨著 vite 的發展，vitepress 已經到了 1.0.0-alpha.22 版本，很多部落格還是基於 0.x 版本，1.0.0 與 0.22 配置略有差別，尤其是一些 vitepress 插件不支援 1.0.0 版本，如 vitepress-theme-demo（用它可以方便的編寫組件 demo）。雖然現在 1.0.0 還是 alpha 版本，咱也可以嘗試使用，反正遇到什麼坑就去填什麼坑就可以了唄。

1 初始化工程

1.1 創建項目

創建目錄（目錄名自己取，這裡我取名為 doc-vitepress-archetype）作為文檔項目的根目錄，在命令行進入該目錄，使用 npm/yarn/pnpm 初始化為 npm 項目（生成 package.json）。

pnpm init

之前看過優雅哥文章的夥伴應該清楚，優雅哥一直習慣使用 yarn，但從本文開始，包管理工具我都換做 pnpm，具體原因在後面的搭建 monorepo 風格組件中再談。

添加 vitepress 為開發依賴：

pnpm install vitepress -D

當前 vitepress 版本為 1.0.0-alpha.22，後面如果發布正式版後有 broken change，咱又更新文章。

1.2 創建目錄及文件

在項目根目錄下創建目錄 docs（這裡的目錄名 docs 與後面配置 package.json 中 scripts 的參數一致），並在 docs 目錄中創建 index.md 文件

# Hello Vitepress

在 docs 目錄下創建公共資源目錄 public，該目錄與 vite vue3 項目的 public 一樣，弄一個 logo.png 到該目錄中。

此時目錄結構為：

doc-vitepress-archetype/
|- docs/
		|- index.md
		|- public/
				|- logo.png
|- package.json

1.3 添加 scripts

在 package.json 中添加項目的啟動、打包、預覽命令：

"scripts": {
  "dev": "vitepress dev docs",
  "build": "vitepress build docs",
  "serve": "vitepress serve docs"
},

dev 是開發模式啟動 vitepress；build 為打包；serve 是對打包後的結果啟動服務預覽。命令參數中的 docs 就是上面在根目錄創建的目錄名 docs。

1.4 啟動服務

在控制台執行 pnpm dev，啟動服務，在頁面訪問控制台輸出的地址，默認該頁面支援 dark/light 切換。頁面如下

dark 模式：

light 模式：

出現上面的介面，則 vitepress 開發環境配置成功。

2 配置 vitepress

接下來便是 vitepress 的配置。

2.1 首頁配置

首先配置文檔首頁，讓其看起來像一個組件庫的首頁。首頁在 index.md 文件中使用 Frontmatter 編寫。Frontmatter 本質上就是在 MD 文件中編寫 yaml 獲取 JSON，位於兩個 — 之間，且必須放在 MD 文件的頂部。可通過 Frontmatter 指定文檔的標題、布局等屬性。具體屬性配置可以在官網上查看：

將 docs/index.md 內容修改如下：

---
layout: home

title: 選項卡標題
titleTemplate: 選項卡描述
editLink: true
lastUpdated: true
hero:
  name: 組件庫名稱
  text: 組件庫文本
  tagline: 組件庫副標題描述
  image:
    src: /logo.png
    alt: YYG Admin UI
  actions:
    - theme: brand
      text: 快速開始
      link: /guide/
    - theme: alt
      text: 組件
      link: /components/
features:
  - icon: 🔨
    title: 功能/特點 1
    details: 功能/特點 1 具體描述資訊。
  - icon: 🧩
    title: 功能/特點 2
    details: 功能/特點 2 具體描述資訊。
  - icon: ✈️
    title: 功能/特點 3。
    details: 功能/特點 3 具體描述資訊。
---

配置和介面的對應關係如下：

關於上面 Frontmatter 的幾點說明：

layout：支援 doc、home、page 三個值，這裡使用 home 布局；
title 和 titleTemplate：在瀏覽器標籤頁上面顯示；
features 中的 icon 目前只支援 emojis 圖標。

2.2 App 配置

在 docs 目錄下新建目錄 .vitepress，在該目錄中創建 config.ts 文件：

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'YYG Admin UI',
  description: '基於 vite vue3 element-plus 組件庫',
  lang: 'cn-ZH',
  base: '/',
  lastUpdated: true
})

2.3 主題配置

主題配置通常用於配置 logo、頂部導航、左側導航等資訊。

在 docs 目錄下創建 guide 和 components 目錄，存放頂部導航的指南和組件兩個菜單，目錄結構如下：

doc-vitepress-archetype/
|- docs/
		|- index.md
		|- public/
				|- logo.png
		|- guide/
				|- index.md
				|- quickstart.md
		|- components/
				|- basic-component1.md
				|- basic-component2.md
				|- common-component1.md
				|- common-component2.md
				|- pro-component1.md
				|- pro-component2.md
|- package.json

1）在 docs/.vitepress/config.ts 中定義頂部導航數據：

import { DefaultTheme, defineConfig } from 'vitepress'

const nav: DefaultTheme.NavItem[] = [
  { text: '指南', link: '/guide/' },
  { text: '組件', link: '/components/basic-component1' },
  // 頂部導航下拉菜單按如下方式：
  /*
  {
    text: 'Dropdown Menu',
    items: [
      { text: 'Item A', link: '/item-1' },
      { text: 'Item B', link: '/item-2' },
      { text: 'Item C', link: '/item-3' }
    ]
  }
   */
]

2）在 docs/.vitepress/config.ts 中定義側邊欄數據：

const sidebar: DefaultTheme.Sidebar = {
  '/guide': [
    {
      text: '指南',
      items: [
        { text: '組件庫介紹', link: '/guide/' },
        { text: '快速開始', link: '/guide/quickstart' },
      ]
    }
  ],
  '/components': [
    {
      text: '通用基礎組件',
      items: [
        { text: '基礎組件 1', link: '/components/basic-component1' },
        { text: '基礎組件 2', link: '/components/basic-component2' }
      ]
    },
    {
      text: '通用業務組件',
      items: [
        { text: '通用組件 1', link: '/components/common-component1' },
        { text: '通用組件 2', link: '/components/common-component2' }
      ]
    },
    {
      text: '高級業務組件',
      items: [
        { text: '高級組件 1', link: '/components/pro-component1' },
        { text: '高級組件 2', link: '/components/pro-component2' }
      ]
    }
  ]
}

3）在 docs/.vitepress/config.ts 中配置主題：

export default defineConfig({
  title: '瀏覽器標題',
  description: '瀏覽器描述',
  lang: 'cn-ZH',
  base: '/',
  lastUpdated: true,
  themeConfig: {
    logo: '/logo.png',
    siteTitle: '組件庫標題',
    outline: 3,
    socialLinks: [
      { icon: 'github', link: '//github.com/vuejs/vitepress' }
    ],
    nav,
    sidebar
  }
})

2.4 預覽效果

啟動服務，預覽效果如下：

本文完成了 vitepress 的首頁和基本配置，下文介紹如何在 vitepress Markdown 文檔中編寫組件 Demo 及展示Demo的程式碼塊。

Tags: vite VUE 前端組件庫