Vue 组件库文档站点的搭建思路

搭建 Vue 组件库文档站点：一份详尽指南

在组件化的时代，建立一个全面的组件库对于提升开发效率至关重要。而一个优秀的组件库离不开一份详尽的文档站点。本指南将深入探讨如何使用 Vue、Vite 和 Vitepress 构建一个专业的 Vue 组件库文档站点，涵盖从环境搭建到自动化部署的各个方面。

环境搭建

安装 Vite

npm install -g vite

初始化项目

vite create vue-component-library

安装 Vitepress

cd vue-component-library
npm install -D vitepress

文档编写

使用 Markdown

Vitepress 使用 Markdown 编写文档。在 docs/ 目录下创建 .md 文件，即可编写文档内容。

使用 Vue 组件

你可以在 Markdown 中直接使用 Vue 组件，例如：

<MyComponent />

多语言路由

创建多语言文件夹

在 docs/ 目录下创建不同的语言文件夹，例如：

docs/
  ├── en
  ├── zh-CN

生成多语言路由

在 vitepress.config.ts 中配置路由：

export default defineUserConfig({
  lang: 'en-US',
  theme: vitepressTheme(),
  srcDir: 'docs',
  srcExclude: [
    'tutorial/**',
    'advanced/**',
  ],
  vite: {
    define: {
      __VUEPRESS_SSR__: true,
    },
    server: {
      port: 3000,
    },
  },
  vueI18n: {
    locale: 'en',
    fallbackLocale: 'en',
    messages: {
      en: {
        message: 'Hello world!',
      },
      'zh-CN': {
        message: '你好，世界！',
      },
    },
  },
})

CI/CD 集成

安装 Git Hooks

npm install -D husky lint-staged

配置 Git Hooks

在 .huskyrc.js 中配置 Git Hooks：

module.exports = {
  hooks: {
    'pre-commit': 'lint-staged',
  },
}

配置 CI/CD

在 package.json 中配置 CI/CD：

{
  "scripts": {
    "build": "vite build",
    "deploy": "gh-pages -b master -d docs/.vitepress/dist"
  },
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.{js,ts,vue}": ["eslint --fix", "git add"]
  },
  "gh-pages": {
    "message": "chore: deploy docs",
    "silent": true,
    "clone": {
      "branch": "gh-pages"
    }
  }
}

组件化开发

创建组件

在 src/components/ 目录下创建 Vue 组件文件，例如：

MyComponent.vue

引入组件

在 .md 文件中引入组件：

<script setup>
import MyComponent from '@/components/MyComponent.vue'
</script>

<template>
  <MyComponent />
</template>

结论

通过本文的指导，你可以轻松搭建一个 Vue 组件库文档站点。从环境搭建到多语言路由，从 Git Hooks 到 CI/CD 集成，再到组件化开发，本文涵盖了整个搭建过程中的关键技术。掌握这些技能，你将能够为你的 Vue 组件库创建一份详尽、易用的文档，为开发者提供良好的使用体验。

常见问题解答

1. 为什么使用 Vitepress 代替 VuePress？

Vitepress 是 VuePress 的一个分支，基于 Vite 构建，具有更好的性能和开发体验。

2. 如何定制文档站点的外观？

你可以修改 vitepress.config.ts 中的 theme 选项来自定义文档站点的主题和样式。

3. 如何使用 Vue Router 在文档站点中创建导航栏？

在 vitepress.config.ts 中配置 router 选项即可使用 Vue Router。

4. 如何为组件库添加示例代码？

你可以使用 CodeSandbox 或 StackBlitz 等在线代码编辑器创建示例代码并将其嵌入文档中。

5. 如何部署文档站点？

你可以使用 gh-pages 命令将文档站点部署到 GitHub Pages，也可以使用其他托管平台，如 Vercel 或 Netlify。