如何使用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 的建设方案也会在后续的文章中与大家分享

原创文章,作者:我心飞翔,如若转载,请注明出处:https://www.pipipi.net/12586.html

发表评论

登录后才能评论