小桥流水78

这个屌丝很懒，什么也没留下！

热门标签

第四章使用Vitepress搭建文档网站_vitepress主题

作者：小桥流水78 | 2024-06-21 00:41:46

踩

vitepress主题

第四章使用Vitepress搭建文档网站

文档建设一般会是一个静态网站的形式，这次采用 Vitepress 完成文档建设工作。

Vitepress 是一款基于Vite 的静态站点生成工具。开发的初衷就是为了建设 Vue 的文档。Vitepress 的方便之处在于，可以使用流行的 Markdown 语法进行编写，也可以直接运行 Vue 的代码。也就是说，它能很方便地完成展示组件 Demo 的任务。

使用 Vitepress 作为文档建设工具还有另外一个好处。由于 Vitepress 是基于 Vite 的，所以它也很好的继承了 Bundless 特性，开发的代码能以“秒级”速度在文档中看到运行效果，完全可以充当调试工具来使用。所以通常情况下我开发组件时，就会直接选择在 Vitepress 上进行调试。这个开发方式大家也可以尝试一下。

本章任务

利用 Vitepress 搭建生成文档网站
引用组件并展示到 Demo
引入代码示例提高阅读体验

【task1】搭建Vitepress生成文档网站

安装开发依赖

pnpm i vitepress -D
1

配置vitepress的vite配置

默认 Vitepress 是无需配置 vitepress.config.ts 的，但是组件库中需要支持 JSX 语法与 UnoCSS，所以就需要添加配置文件。

文件名：docs/vite.config.ts

import { defineConfig } from "vite";
import vueJsx from "@vitejs/plugin-vue-jsx";
import Unocss from "../config/unocss";
// https://vitejs.dev/config/

export default defineConfig({
  plugins: [
    // 添加JSX插件
    vueJsx(),
    Unocss(),
  ],
    // 这里变更一下端口
  server: {
    port: 3000
  }
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

创建文档首页

文件名：docs/index.md

## hello Vitepress

```ts
const str:string = "hello vitepress"

```
1
2
3
4
5
6

增加文档启动脚本

{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:serve": "vitepress serve docs"
  }
}
1
2
3
4
5
6
7

运行文档站点

pnpm docs:dev
1

在浏览器查看结果

vitepress v1.0.0-alpha.28

  ➜  Local:   http://localhost:3000/
  ➜  Network: use --host to expose

1
2
3
4
5

在这里报了一个错误：

[unocss] entry module not found, have you add `import 'uno.css'` in your main entry?
1

这里重启一下项目。至此vitePress测试成功。

【task2】引用组件并展示到 Demo

docs
 |--- .vitepress
 |		|--- theme
 |		|     |--- index.ts
 |		|--- config.ts
 |--- components
 |      |--- button
 |      |      |--- index.md
 |      |--- index.md
 |      | ...
 |--- index.md
 |--- vite.config.ts
1
2
3
4
5
6
7
8
9
10
11
12

子菜单所对应的 markdwon 文件路径(默认页面 index.md)

配置菜单项

文件名：docs/.vitepress/config.ts

const sidebar = {
  '/': [
    {
      text: 'Guide',
      items: [
        { text: '快速开始', link: '/' }, 
        { text: '通用', link: '/components/button/' }, 
      ]
    }
  ]
}
const config = {
  themeConfig: {
    sidebar,
  }
}
export default config
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

在主题中引入组件

文件名：docs/.vitepress/theme/index.ts

import Theme from 'vitepress/dist/client/theme-default/index.js'
import SmartyUI from '../../../src/entry'

export default {
  ...Theme, // 默认主题
  enhanceApp({ app }) {
    app.use(SmartyUI)
  },
}
1
2
3
4
5
6
7
8
9

编写组件文档

文件名：docs/components/button/index.md

# Button 按钮

  <div style="margin-bottom:20px;">
    <SButton color="blue">主要按钮</SButton>
    <SButton color="green">绿色按钮</SButton>
    <SButton color="gray">灰色按钮</SButton>
    <SButton color="yellow">黄色按钮</SButton>
    <SButton color="red">红色按钮</SButton>
  </div>
1
2
3
4
5
6
7
8
9

重启文件站点

pnpm docs:dev
1

浏览器查看结果

vitepress v1.0.0-alpha.28

  ➜  Local:   http://localhost:3000/
  ➜  Network: use --host to expose
1
2
3
4

在这里插入图片描述

【task3】引入组件代码提高阅读

修改sidebar