VitePress 构建组件库文本文档

VitePress 构建组件库文本文档

在我们组件库完成情况下,一个详尽的使用文档是不可缺少的。本文将详细介绍怎么使用 VitePress 迅速搭建一个组件库文本文档网站并部署到GitHub上

组装

最先新创建 site 文件夹名称,并实施pnpm init,随后组装vitepress和vue

pnpm install -D vitepress vue

安装完成以后,新创建 docs/index.md 文档

# Hello Easyest

随后 package.json 中新增加scripts指令

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

实行pnpm run docs:dev

导航条配备

在 docs/.vitepress 文件目录下新建config.js

export default {
  themeConfig: {
    siteTitle: "vitepress",
    nav: [
      { text: "手册", link: "/guild/installation" },
      { text: "部件", link: "/components/button/" },
    ],
    socialLinks: [
      { icon: "github", link: "https://github.com/qddidi/easyest" },
    ],
  },
};

接下来我们添加了2个导航条和一个 github 详细地址,重新启动新项目就能看到导航条早已起效了

可是点一下手册和部件是 404,由于我们还没建立这种文件目录和文档。所以我们需要在 docs 文件目录下新建guild/index.md及其components/button/index.md,再度点一下就可以自动跳转相匹配网页页面

侧栏配备

一样在config.js内进行侧栏配备sidebar

   sidebar: {
            "/guild/": [
                {
                    text: "基本",
                    items: [
                        {
                            text: "组装",
                            link: "/guild/installation",
                        },
                        {
                            text: "快速开始",
                            link: "/guild/quickstart",
                        },
                    ],
                },
                {
                    text: "升阶",
                    items: [
                        {
                            text: "xx",
                            link: "/xx",
                        },
                    ],
                },
            ],
            "/components/": [
                {
                    text: "基础组件",
                    items: [
                        {
                            text: "Button",
                            link: "/components/button",
                        }
                    ],
                }
            ]
        },

这时也就有了侧栏

引进组件库

由于我们应该构建的是一个组件库文本文档网站,因而一定是必须引进我们自己的组件库的。这儿我们同样引进是指当地的组件库,因此在 pnpm 的办公空间pnpm-workspace.yaml新增加一个site文件目录

packages:
  - "packages/**"
  - "play"
  - "site"

随后 site 目录下组装pnpm add easyest,在 docs 下新建 theme/index.js引进我们自己的组件库

import DefaultTheme from "vitepress/theme";
import easyest from "easyest";
export default {
  ...DefaultTheme,
  enhanceApp: async ({ app }) => {
    // app is the Vue 3 app instance from `createApp()`. router is VitePress'
    // custom router. `siteData`` is a `ref`` of current site-level metadata.
    app.use(easyest);
  },
};

返回 components/button/index.md 中直接用我们自己的 button 部件试一下

## Button 按键

<ea-button>默认设置按键</ea-button>

<ea-button type="primary">默认设置按键</ea-button>

不难发现我们自己的部件起效了

与此同时我们也可以新增加代码展示实际效果,或者将 button/index.md 改成

## Button 按键

<ea-button>默认设置按键</ea-button>
<ea-button type="primary">默认设置按键</ea-button>

::: details 表明编码

```html
<ea-button>默认设置按键</ea-button> <ea-button type="primary">默认设置按键</ea-button>
```

:::

是否比较简单!

布署静态数据网站

打包完成后你能部署到自己的网站,还可以选择部署到 github 网站上,这里将详细介绍怎样部署到 github 网站

最先新创建一个组织称为easyestui,然后机构下新建一个easyest库房

再将 site/docs/.vitepress/dist 提交到这一仓库中

点一下 settings 挑选部署的支系及其文件目录,欢迎来到网站根目录,储存就可以

最后大家站点浏览地址为 easyestui.github.io/easyest/ 因此在装包时 site/docs/.vitepress/config.js 的 base 应该给/easyest/

export default {
    base: process.env.NODE_ENV === 'production' ? '/easyest/' : '/',
   ...
}

之上完毕之后便能浏览我们自己的网站了 Easyest,网站是自动更新的,如果你的库房发生变化网站便会更改

留意:假如你浏览出现404,那可能是你base配备出错了

本文相匹配仓库地址: VitePress 构建布署组件库文本文档