如何使用vitepress写一套自己的ui文档

在vue3.0 热潮涌动的背后,尤大默默的发布了 vite1.0.beta版本。vite算是为未来而生的,它采用的es module进行模块导入,省去了build过程。这对于大型项目来说将会是巨大的福音。下面我将给大家讲讲我是如何一步步使用vitepress 以及遇到的问题是如何处理的。

下面是项目地址:
vitepress docs
vitevui 基于rollup开发的兼容vite的ui框架
vitevuu 基于rollup开发的工具库

vite

vite采用的es module进行模块导入,这是现代浏览器原生支持的,当import一个模块时,会发出一个请求,正因如此,只能在服务中使用es module。而且import的模块路径发生变化的时候,会重新发送请求,路径变化包括query。

vitepress

安装

  • 第一步:创建目录
    mkdir vitepress-starter && cd vitepress-starter
 
  • 第二步:vitepress 首选推荐使用yarn 创建包管理工具进行初始化
    yarn init
 
  • 第三步:本地安装vitepress
    yarn add --dev vitepress
 
  • 第四步:创建你的第一个文档
    mkdir docs && echo '# Hello VitePress' > docs/index.md
 
  • 第五步:给package.json添加相关命令
    {
      "scripts": {
        "docs:dev": "vitepress dev docs",
        "docs:build": "vitepress build docs",
        "docs:serve": "vitepress serve docs"
      }
    }
 
  • 第六步:本地运行vitepress

这个时候我们就能通过打开 http://localhost:3000/ 进行查看

    yarn docs:dev
 

目录结构

下面是我写好的目录结构

├── .vitepress
│   ├── config.js
│   └── theme
│       ├── components
│       │   └── contentmenu.vue
│       ├── index.js
│       └── style.less
├── README.md
├── components
│   ├── button
│   │   └── index.md
│   ├── contextmenu
│   │   └── index.md
│   ├── layout
│   │   └── index.md
│   └── log.md
├── docs.md
├── index.md
├── tags.md
└── vuu
    ├── any.md
    ├── index.md
    └── log.md
 

vitepress 配置

./vitepress/config.js, 下面展示的是根据我自己开发需求而配置。
点击查看 vitepress 生成的文档
基本的配置我就不讲了,主要分享下 sidebar, 侧边栏的配置

module.exports = {
  head: [
    [
      'meta',
      {
        name: 'viewport',
        content:
          'width=device-width,initial-scale=1,minimum-scale=1.0,maximum-scale=1.0,user-scalable=no',
      },
    ],
    ['meta', { name: 'keywords', content: 'vite vui' }],
    ['link', { rel: 'icon', href: '/favicon.ico' }],
  ],
  title: 'Vite vui',
  base: '/vite-vui-docs/',
  themeConfig: {
    search: true,
    sidebar: {
      '/': [
        {
          text: 'vui',
          children: [
            { text: '介绍', link: '/' },
            { text: '日志', link: '/components/log' },
            { text: 'Button', link: '/components/button/' },
            { text: 'Layout', link: '/components/layout/' },
            { text: 'contextmenu', link: '/components/contextmenu/' },
          ],
        },
        {
          text: 'vuu',
          children: [
            { text: '介绍', link: '/vuu/' },
            { text: '日志', link: '/vuu/log' },
            { text: '某个功能', link: '/vuu/any' },
          ],
        },
      ],
    },
    author: 'bhabgs',
    nav: [
      { text: '首页', link: '/' },
      { text: '分类', link: '/tags' },
    ],
  },
  dest: 'public',
};

 

sidebar

sidebar是用来配置侧边栏的,siderbar 与vuepress的配置相差不多,主要在 link上使用会有一些问题,当连接文件夹下的./components/layout/index.md 时 需要使用 /components/layout/, 如果连接的是layout.md 那么 link需要写成 /components/layout

问题

这块主要记录了在使用vitepress 的过程中遇到的相关问题。

  1. 当你的ui工具存在v-* 的用户自定义指令后,并且在vitepress中引入了在.md或者vue组件中使用时,会提示如下错误。vue官方提供了相关解决方案 安装该补丁patch-vue-directive-ssr能过解决该问题 问题原因可点击查看,相信在vitepress 1.0正式版本发布后就不会有该问题了。

custom directive is missing corresponding SSR transform and will be ignored.,

*** 问题持续更新中

vitevui、vitevuu 的建设方案也会在后续的文章中与大家分享

(0)
上一篇 2021年3月27日 上午11:44
下一篇 2021年3月27日 下午12:00

相关推荐

发表评论

登录后才能评论