【二】组件库文档系统

携手创作，共同成长！这是我参与「掘金日新计划 · 8 月更文挑战」的第12天，点击查看活动详情

文档系统

我们基于 vitepress 搭建组件库文档系统。

一、安装依赖

pnpm add -D vitepress

vitepress 是基于 vite 的，请确保你的项目是 vite 搭建的

二、实现第一个文档demo

在根目录下执行：mkdir docs && echo # Hello VitePress > docs/index.md

相当于：创建 docs 文件夹，并在其中的 index.md 文件中写入 # Hello VitePress

如下图所示：

三、预览md文件

现在，我们想用 vitepress 将文件系统跑起来，在页面上预览我们的 md 文件

• 添加 script 脚本命令（package.json）

使用 vitepress 的 dev（开发）模式，启动 docs 文件夹下的所有内容。它会识别 md 文件，将其变为页面。

同理，build 和 serve 分别代表 “打包” 和 “生成版本预览”

{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:serve": "vitepress serve docs"
  },
}

• 现在我们可以尝试预览一下了

执行脚本 npm run docs:dev，然后在相应的端口（我这里是3000），就可以看到我们的页面了

四、侧边栏及组件显示配置

在 docs 下创建 .vitepress 文件夹，继续在其中创建 config.ts 文件，写入如下内容

import { defineConfig } from "vitepress";

const sidebar = {
  "/": [
    { text: "快速开始", link: "/", items: [] },
    {
      text: "通用",
      items: [{ text: "Button 按钮", link: "/components/button/" }],
    },
  ],
};

export default defineConfig({
  themeConfig: {
    sidebar,
  },
});

• 创建 button

在 docs 下新建文件 docs/components/button/index.md

# Button

我们再来观察一下此时的页面：可以看到导航栏内容已经显示了。

五、显示组件

修改 button/index.md 文件

# Button
<HelloWorld></HelloWorld>

markdown 文件中，组件该如何解析以及显示呢？

• 添加vite配置：docs/vite.config.ts

import { defineConfig } from "vite";
import VueJsx from "@vitejs/plugin-vue-jsx";

export default defineConfig({
  plugins: [VueJsx()],
});

• 添加类型文件：docs/docs.d.ts

declare module "*.vue" {
  import type { DefineComponent } from "vue";
  const component: DefineComponent<{}, {}, any>;
  export default component;
}

• 添加样式文件：docs/.vitepress/theme/index.ts

import Theme from "vitepress/theme";
import HelloWorld from "../../../src/components/HelloWorld.vue";

export default {
  ...Theme,
  // 扩展应用程序实例
  enhanceApp({ app }) {
    // 注册组件
    app.component("HelloWorld", HelloWorld);
  },
};

此时再来看页面，可以发现 HelloWorld 已经在 Button 页面中显示了

六、显示组件代码

• 安装插件

pnpm add -D vitepress-theme-demoblock

• 修改配置：docs/.vitepress/theme/index.ts

import { demoBlockPlugin } from "vitepress-theme-demoblock";
export default defineConfig({
  themeConfig: {
    sidebar,
  },
  markdown: {
    config(md) {
      // 这里可以使用markdown-it插件
      md.use(demoBlockPlugin);
    },
  },
});

• 注册组件：.vitepress/theme/index.ts

import Theme from "vitepress/theme";
import HelloWorld from "../../../src/components/HelloWorld.vue";

import DemoBlock from "vitepress-theme-demoblock/components/DemoBlock.vue";
import Demo from "vitepress-theme-demoblock/components/Demo.vue";

export default {
  ...Theme,
  // 扩展应用程序实例
  enhanceApp({ app }) {
    // 注册组件
    app.component("DemoBlock", DemoBlock);
    app.component("Demo", Demo);

    app.component("HelloWorld", HelloWorld);
  },
};

• 修改组件文档：docs/components/button/index.md

# Button

:::demo 这是HelloWorld组件，我们可以传入msg属性给它
```vue
<template>
  <HelloWorld></HelloWorld>
</template>
```
:::

现在重启项目，可以看到页面的组件信息了