今天是2024年的最后一天，在这里提前祝大家2025新年快乐！年终将至，很多小伙伴可能正在忙着准备公司年终总结和汇报。大家年初定下的KPI完成得怎么样了？我已经顺利完成了所有任务，并完成了汇报。在我的年终汇报中，作为一名程序员，我没有单纯地列举写了多少代码，做了哪些库，而是将所有工作通过 VitePress 进行了整合和包装。在汇报时，我直接拿出精心准备的文档，轻松展示了一番，效果还不错哦 😂 言归正传，接下来，我将全面介绍VitePress，并与大家分享如何用它展示组件库文档中的组件示例功能。 ## 一、什么是 VitePress VitePress 是由 Vue.js 官方团队开发的一款基于 Vite 的静态站点生成器。它通过 Vue 3 提供了现代化的开发体验，并且专注于文档的构建，支持 Markdown 格式的内容编辑。 * **性能优异**：基于 Vite，启动和构建速度非常快。 * **支持 Vue 3**：可以轻松将 Vue 组件嵌入文档中，适合开发者编写互动式文档。 * **简单易用**：配置简洁，易于上手，适合快速构建小型站点。 ![screencapture-vitepress-dev-zh-2024-12-30-14\_51\_32.png](https://p6-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/cf0dfd3aee9845448a1d381d03e4abbd~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg5oiR5LiN5Y-r546L5bCP57qi:q75.awebp?rk3s=f64ab15b&x-expires=1772489217&x-signature=EQHLUhxEYuiAn86FyE4yqaD84oQ%3D) ## 二、VitePress 环境搭建 ### 1. 安装 VitePress 首先，确保你已经安装了 [Node.js](https://nodejs.org/) 18 及以上版本。运行下面的命令，在你的项目中安装 VitePress： ```bash npx vitepress init ``` 需要回答一些问题： ```bash ┌ Welcome to VitePress! │ ◇ Where should VitePress initialize the config? │ ./docs │ ◇ Site title: │ My Awesome Project │ ◇ Site description: │ A VitePress Site │ ◆ Theme: │ ● Default Theme (Out of the box, good-looking docs) │ ○ Default Theme + Customization │ ○ Custom Theme └ ``` 或者，如果你想将其添加到现有项目中，运行下面的命令，但是这不会自动帮你创建目录。 ```bash npm add -D vitepress ``` ### 2. 创建基本项目结构如果正在构建一个独立的 VitePress 站点，可以在当前目录 (`./`) 中搭建站点。但是，如果在现有项目中与其他源代码一起安装 VitePress，建议将站点搭建在嵌套目录 (例如 `./docs`) 中，以便它与项目的其余部分分开。假设选择在 `./docs` 中搭建 VitePress 项目，生成的文件结构应该是这样的： ```bash . ├─ docs │ ├─ .vitepress │ │ └─ config.js │ ├─ api-examples.md │ ├─ markdown-examples.md │ └─ index.md └─ package.json ``` `docs` 目录作为 VitePress 站点的项目**根目录**。`.vitepress` 目录是 VitePress 配置文件、开发服务器缓存、构建输出和可选主题自定义代码的位置。 ### 3. 启动开发服务器在项目根目录下运行如下命令： ```bash npx vitepress dev docs ``` 服务启动后，可以运行控制台输出的地址，默认是 `http://localhost:5173`。 ### 4. 配置启动命令将如下命令配置到你的 `package.json` 中。 ```json { ... "scripts": { "docs:dev": "vitepress dev docs", "docs:build": "vitepress build docs", "docs:preview": "vitepress preview docs" }, ... } ``` ## 三、VitePress 基础配置 VitePress 的核心配置文件是 `.vitepress/config.ts`，它允许你自定义站点的基础设置，包括站点标题、描述、导航栏、侧边栏等内容。这些配置项让你能够快速定制文档站点的外观与结构。 ### 1. 配置文件示例 ```ts // .vitepress/config.ts import { defineConfig } from 'vitepress' export default defineConfig({ // 站点的标题 title: '文档标题', // 站点的描述 description: '文档描述', themeConfig: { // 导航栏配置 nav: [ { text: '首页', link: '/' }, { text: '指南', link: '/guide' } ], // 侧边栏配置 sidebar: { '/': [ { text: '首页', link: '/' }, { text: '指南', link: '/guide' } ] } } }) ``` 在上述配置中，你可以： * 设置站点的 `title` 和 `description`，分别用于定义文档站点的标题和描述。 * 配置 `themeConfig` 来定制导航栏（`nav`）和侧边栏（`sidebar`），让文档的结构更加清晰和易于导航。 ### 2. 自定义主题与样式除了基础配置，VitePress 还支持主题自定义。你可以在 `.vitepress/theme/` 目录下创建自定义的样式文件或 Vue 组件，从而调整站点的布局、颜色、字体等外观。例如，你可以在 `index.ts` 文件中修改主题： ```ts // .vitepress/theme/index.ts import DefaultTheme from 'vitepress/theme' import './custom.css' // 引入自定义样式 export default { ...DefaultTheme, // 保留默认主题的功能和样式 } ``` 通过这种方式，你不仅能定制文档站点的基本结构，还能调整视觉效果，创建符合需求的独特外观。 ## 四、国际化站点配置 VitePress 内置了国际化支持，配置过程非常简单，无需额外插件。只需要调整目录结构并更新 `config.ts` 配置文件，即可实现多语言支持。 ### 1. 调整目录结构首先，按需调整 `docs` 目录来划分不同语言版本的文档。例如，以下是一个典型的目录结构： docs/ ├─ es/ │ ├─ foo.md ├─ fr/ │ ├─ foo.md ├─ foo.md 为了更清晰的组织不同语言的内容，我们可以将文档目录调整为： docs/ ├─ en/ │ ├─ index.md ├─ zh/ │ ├─ index.md ### 2. 拆分配置文件为了更好地管理不同语言的配置，可以将 `.vitepress/config.ts` 文件拆分成多个文件，每个文件负责一种语言的配置。最终的目录结构如下： .vitepress/ ├─ config/ │ ├─ zh.ts │ ├─ en.ts │ ├─ shared.ts │ ├─ index.ts 拆分后的配置文件变得更加清晰和可扩展，尤其对于大型项目，能提高配置的可维护性与复用性。 ### 3. 入口文件配置在 `.vitepress/config/index.ts` 中导入并合并各个语言的配置，以及共享配置，最终输出完整的站点配置。 ```ts // .vitepress/config/index.ts import { defineConfig } from 'vitepress' import { en } from './en' import { shared } from './shared' import { zh } from './zh' export default defineConfig({ ...shared, locales: { root: { label: 'English', ...en }, zh: { label: '中文', ...zh }, }, }) ``` ### 4. 共享配置文件共享配置文件 `shared.ts` 包含了所有语言通用的设置，比如站点的标题、favicon、社交链接等。它可以提高配置的复用性。 ```ts // .vitepress/config/shared.ts import { defineConfig } from 'vitepress' export const shared = defineConfig({ title: '文档标题', rewrites: { 'en/:rest*': ':rest*', }, lastUpdated: true, cleanUrls: true, metaChunk: true, head: [ ['link', { rel: 'icon', href: '/favicon.ico' }], ['link', { rel: 'icon', type: 'image/png', href: '/logo.png' }], ['meta', { property: 'og:type', content: 'website' }], ['meta', { property: 'og:locale', content: 'en' }], ['meta', { property: 'og:title', content: '文档标题' }], ['meta', { property: 'og:site_name', content: '文档标题' }], ['meta', { property: 'og:image', content: '/logo.png' }], ], themeConfig: { logo: '/logo.png', socialLinks: [ { icon: 'github', link: 'https://github.com/kieranwv' }, ], search: { provider: 'local', }, }, markdown: { theme: { light: 'github-light', dark: 'github-dark', }, }, }) ``` ### 5. 中文文档配置 `zh.ts` 配置文件专门用于中文文档的配置，它包括语言设置、描述、导航、侧边栏等内容。 ```ts // .vitepress/config/zh.ts import { defineConfig } from 'vitepress' import pkg from '../../../package.json' export const zh = defineConfig({ lang: 'zh-CN', description: '文档描述', themeConfig: { editLink: { pattern: '', text: '在 GitHub 上编辑此页面', }, nav: [ { text: '顶部导航', link: '/zh/01/01', activeMatch: '/zh/01/' }, { text: '顶部导航', link: '/zh/02/01', activeMatch: '/zh/02/' }, { text: `v${pkg.version}`, items: [ { text: 'Changelog', link: '', }, ], }, ], sidebar: [ { text: '侧面导航', collapsed: false, items: [ { text: '标题', link: '/zh/01/01' }, { text: '标题', link: '/zh/01/02' }, ], }, { text: '侧面导航', collapsed: false, items: [ { text: '标题', link: '/zh/02/01' }, ], }, ], footer: { message: '基于 MIT 许可证发布。', copyright: '版权 © 2024-present Kieran Wang', }, }, }) ``` ### 6. 英文文档配置对于英文文档，只需修改与语言相关的内容，其他部分可以复用中文配置的内容。 ### 7. 文档书写完成配置后，只需根据新的目录结构在 `docs/` 目录下编写各语言版本的文档。每个语言版本都拥有独立的 Markdown 文件，可以灵活地管理和维护不同语言的内容。 ## 五、使用 Vue 组件在组件库的文档中，通常会提供 **可交互的组件示例** 和 **源代码示例**，以便帮助用户理解组件的使用方法，并能直接复制到自己的项目中。VitePress 提供了一种灵活的方式来展示这些组件及其源代码。 ### 1. 在 VitePress 中使用 Vue 组件 VitePress 使用 Vue 单文件组件（SFC）处理 Markdown 文件，这意味着在 Markdown 中可以直接使用 Vue 的功能，包括动态模板、Vue 组件和通过 ` ## Markdown 内容当前计数值是：{{ count }} ``` 在这个例子中，` ``` 接着，在 Markdown 文件中引用这个组件： ```md # 文档内容这是一个使用自定义组件的文档示例： ## 更多文档内容 ... ``` VitePress 会自动识别并渲染该 Vue 组件，显示组件的实际效果。只要组件文件正确导入，VitePress 就会处理它并在文档中呈现。 ### 3. 显示源代码除了展示可交互的组件外，VitePress 还允许在文档中展示源代码。例如，如果你想展示上面的 Vue 组件源代码，可以使用 VitePress 的内置代码高亮功能。 VitePress 会自动高亮显示代码块，并使其更具可读性。 ![image.png](https://p6-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/e197364f9d83401cb5f1c948abb0fd89~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg5oiR5LiN5Y-r546L5bCP57qi:q75.awebp?rk3s=f64ab15b&x-expires=1772489217&x-signature=bziai83fimUcmIth3oKZdO07vgU%3D) 更多高亮效果，参考。 ### 4. 全局注册 Vue 组件如果你希望在所有文档中都使用某个组件，可以将其注册为全局组件。在 VitePress 中，你可以通过扩展默认主题来实现这一点。具体的注册方式可以参考 [VitePress 官方文档](https://vitepress.dev/zh/guide/extending-default-theme#registering-global-components)。 ## 六、使用插件和自动化展示 Vue 组件在前端组件库的文档中，我们经常见到组件的示例和代码。 ![image.png](https://p6-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/749778d65b8d4993b55bfab2e6eb6036~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg5oiR5LiN5Y-r546L5bCP57qi:q75.awebp?rk3s=f64ab15b&x-expires=1772489217&x-signature=p2M%2Fz%2B2jgg%2FQ8k4TDR0iPUpUnz8%3D) 为了在 VitePress 中展示可交互的 Vue 组件及其源代码，我们将使用两个插件：`markdown-it` 和 `markdown-it-container`。这两个插件将帮助我们在 Markdown 中嵌入自定义组件，并且支持高亮显示源代码。作者实现的效果如下： ![screencapture-starter-lib-vue3-netlify-app-zh-components-say-hello-2024-12-30-14\_54\_45.png](https://p6-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/87dd0344124e4469ba283bd7deba94e2~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg5oiR5LiN5Y-r546L5bCP57qi:q75.awebp?rk3s=f64ab15b&x-expires=1772489217&x-signature=RhNT3RB40NUFL8t7YYagtNAjg9w%3D) ### 1. 安装插件首先，安装 `markdown-it` 和 `markdown-it-container` 插件： ```sh npm install markdown-it markdown-it-container shiki @types/markdown-it ``` ### 2. 注册插件在 `.vitepress/plugins` 目录下，创建 `index.ts` 和 `markdown.ts` 文件，来注册和配置这些插件。 **`.vitepress/config/index.ts`** import { defineConfig } from 'vitepress' import { nav, repoMasterUrl, repoUrl, sidebar } from './constants' import { MarkdownPlugin } from './plugins' export default defineConfig({ markdown: { config: md => MarkdownPlugin(md), theme: { light: 'github-light', dark: 'github-dark', }, }, }) **`.vitepress/plugins/markdown.ts`** ```ts import type MarkdownIt from 'markdown-it' import type Renderer from 'markdown-it/lib/renderer.mjs' import type Token from 'markdown-it/lib/token.mjs' import { readFileSync } from 'node:fs' import { resolve } from 'node:path' import { cwd } from 'node:process' import markdownItContainer from 'markdown-it-container' import { createHighlighter } from 'shiki' interface ContainerOpts { marker?: string validate?: (params: string) => boolean render?: ( tokens: Token[], index: number, options: any, env: any, self: Renderer ) => string } export async function MarkdownPlugin(md: MarkdownIt): Promise { const highlighter = await createHighlighter({ themes: ['github-light', 'github-dark'], langs: ['vue', 'vue-html', 'typescript', 'javascript'], }) md.use(markdownItContainer, 'example', { validate(params) { // eslint-disable-next-line regexp/no-super-linear-backtracking return !!params.trim().match(/^example\s*(.*)$/) }, render(tokens, idx) { if (tokens[idx].nesting === 1) { let source = '' const sourceFileToken = tokens[idx + 2] const sourceFile = sourceFileToken.children?.[0].content ?? '' if (sourceFileToken.type === 'inline') { source = readFileSync( resolve(cwd(), 'docs/examples', `${sourceFile}.vue`), 'utf-8', ) } if (!source) { throw new Error(`Incorrect source file: ${sourceFile}`) } const shikiSource = highlighter.codeToHtml(source, { lang: 'vue', themes: { light: 'github-light', dark: 'github-dark', }, }) return `` } else { return '' } }, } as ContainerOpts) } ``` ### 3. 用于展示组件示例的 `Example.vue` `Example.vue` 组件展示了如何渲染 Vue 组件并切换源代码的显示。 ### 5. `ExampleOperate.vue` 操作按钮组件 `ExampleOperate.vue` 提供源码显示、复制及打开功能。 ```vue ``` ### 6. `ExampleComponent.vue` 渲染组件 `ExampleComponent.vue` 负责渲染组件并显示交互效果。 ```vue ``` ### 7. `ExampleSourceCode.vue` 组件 `ExampleSourceCode.vue` 负责展示源码内容。 ```vue ``` *** 通过上述配置，我们不仅能够展示 Vue 组件，还能交互式地查看和复制源代码。 ### 7. 实现效果作者提供了在线演示地址： > 这是一个 Vue 3 组件库启动模板，提供 VitePress 文档，支持构建 ESM、CJS 和 IIFE 格式。 > > 仓库地址： > > 在线演示： ![screencapture-starter-lib-vue3-netlify-app-zh-components-say-hello-2024-12-30-14\_54\_45.png](https://p6-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/6f67eec4e1904aa2a695d68d3f1a46ee~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg5oiR5LiN5Y-r546L5bCP57qi:q75.awebp?rk3s=f64ab15b&x-expires=1772489217&x-signature=YDq%2BOHLC4nicgJpR4G5zMM5liM8%3D) ## 七、总结 VitePress 是一个基于 Vite 的静态网站生成器，专注于提供快速构建和优异的开发体验。它通过支持 Markdown 文件与 Vue 组件的结合，使得开发者能够轻松创建交互性强的文档网站。VitePress 内置了国际化支持，能够方便地管理多语言版本的站点，且主题定制能力强，用户可以根据需求调整站点的外观和功能。通过插件系统，开发者还可以扩展更多自定义功能，如代码高亮、交互示例等。此外，VitePress 生成的站点是纯静态的，部署非常便捷，适用于 GitHub Pages、Netlify 等平台。 ## 参考 * [VitePress 官方文档](https://vitepress.dev/) * [Vue 3 组件库启动模板](https://starter-lib-vue3.netlify.app/)