优雅简洁，构建专属组件文档库！ vitepress 轻松入门

2023-11-28 01:09:21

随着前端开发的日益复杂，组件库已成为构建前端应用的利器。它们封装了可复用的组件，让开发人员无需重复造轮子，大大提高了开发效率。然而，组件库的有效使用离不开完善的文档。清晰、详细的组件文档能够帮助开发人员快速理解和使用组件，从而提高开发效率。

vitepress 是一个基于 Vite 的文档生成器，专门用于构建组件库文档。它提供了简洁易用的语法和丰富的功能，帮助开发者轻松创建美观、交互式文档。本文将详细介绍如何使用 vitepress 从零开始搭建一个组件库文档库。

1. 项目准备

1.1 环境要求

Node.js v16.13.0 以上
npm v8.1.0 以上

1.2 项目创建

新建文件夹 vitepress-demo，然后进入到创建好的目录。

cd vitepress-demo

1.3 初始化项目

npm init vitepress@latest

2. 组件管理

2.1 创建组件目录

在项目根目录下创建 components 目录，用于存放组件。

2.2 创建组件

在 components 目录下创建组件文件，例如 Button.vue。

// Button.vue
<template>
  <button>
    <slot />
  </button>
</template>

<script>
export default {
  name: 'Button',
};
</script>

3. 文档编写

3.1 创建文档目录

在项目根目录下创建 docs 目录，用于存放组件文档。

3.2 创建文档文件

在 docs 目录下创建组件文档文件，例如 Button.md。

# Button

组件库中的按钮组件，提供多种样式和尺寸。

## 用法

```html
<template>
  <Button>Click Me</Button>
</template>

<script>
import Button from 'components/Button.vue';

export default {
  components: { Button },
};
</script>

属性

属性	类型	默认值	说明
type	string	'button'	按钮类型
size	string	'medium'	按钮尺寸
color	string	'primary'	按钮颜色

事件

事件	参数	说明
click	无	按钮被点击时触发

样式

.btn {
  padding: 10px 20px;
  border: 1px solid #ccc;
  border-radius: 5px;
  background-color: #eee;
  color: #333;
}

.btn--primary {
  background-color: #007bff;
  color: #fff;
}

.btn--large {
  font-size: 1.2rem;
}

.btn--small {
  font-size: 0.8rem;
}

示例

<template>
  <div>
    <Button type="primary" size="large">Primary</Button>
    <Button type="primary" size="medium">Primary</Button>
    <Button type="primary" size="small">Primary</Button>
  </div>
</template>

<script>
import Button from 'components/Button.vue';

export default {
  components: { Button },
};
</script>