Vitepress搭建組件庫檔案（上）—— 基本配置-有解無憂

在 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: 'https://github.com/vuejs/vitepress' }
    ],
    nav,
    sidebar
  }
})

2.4 預覽效果

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

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

轉載請註明出處，本文鏈接：https://www.uj5u.com/qiye/519310.html

標籤：其他

上一篇：記錄--從原理分析vue開發環境搭建的全部程序

下一篇：面試個人摸底監測考察考察JS三座?? 1. 原型和原型鏈 2. 作?域與閉包 3. 異步和單執行緒（第四天）