当前位置：首页>编程语言>正文

vuepress 实时显示组件效果 vuepress插件开发

编程语言2024-04-30 21:40:27

vuepress编写API文档

介绍
搭建

安装
初始化

配置
组件API文档
发布组件库
坑

没有高亮

介绍

想要搭建一个类似elementUI的组件库及相关的API文档，可以直接引用组件，还有代码展示，这里使用vuepress来搭建。详细配置可以前往vuepress官网查看。

搭建

安装

全局安装vuepress

npm i vuepress -g

新建项目

mkdir my_vuepress

初始化

进入项目

cd my_vuepress

初始化项目

npm init

新建docs

mkdir docs

设置package.json

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

使用，npm run docs:dev（或者vuepress dev docs）运行项目，打开本地地址。

因为，当前文件夹docs中还没有内容，所以运行后内容为空：

vuepress 实时显示组件效果 vuepress插件开发,vuepress 实时显示组件效果 vuepress插件开发_vuepress 实时显示组件效果,第1张

此时，在docs文件夹中新建一个README.md文件，重启项目：

vuepress 实时显示组件效果 vuepress插件开发,vuepress 实时显示组件效果 vuepress插件开发_vuepress 实时显示组件效果_02,第2张

到此为止项目已经搭建完成，但是我们想要的是左边导航，查看不同组件的API文档，头部展示不同的分类，下面继续进行配置。

配置

创建docs/.vuepress文件夹

cd docs
mkdir .vuepress

在.vuepress中新建config.js文件，到此为止项目结构如下：

my_vuepress
├─── docs
│   ├── README.md
│   └── .vuepress
│       └── config.js
└── package.json

头部信息和导航栏

// docs/.vuepress/config.js
module.exports = {
  title: '网宿Web',
  description: 'Just playing around',
  head: [],
  themeConfig: {
    nav: [
      { text: '主页', link: '/' },
      { text: 'ns-UI', link: '/ns-ui/' },
      { text: '开发规范', link: '/standard/'},
      { text: '百度', link: 'http://www.baidu.com' }
    ],
    sidebar: {
      '/ns-ui': [
        {
          title: '开发指南',
          collapsable: false,
          children: [
            '../ns-ui/logs/',
            '../ns-ui/guid/',
            '../ns-ui/install/',
            '../ns-ui/start/'
          ]
        },
        {
          title: '组件',
          collapsable: false,
          children: [
            ['../ns-ui/searchSelect/', 'SearchSelect 选择器']
          ]
        }
      ],
      '/standard': [
        { 
          title: '前端开发规范',
          collapsable: false,
          children: [
            '../standard/html/',
            '../standard/css/',
            '../standard/js/',
            '../standard/vue/',
            '../standard/eslint/'
          ]
        }
      ]
    }
  }
}

文件结构

my_vuepress
├─── docs
│   ├── README.md
│   └── .vuepress
│       └── config.js
│   └── ns-ui
│       └── guid
│       	└── README.md
│       └── install
│       	└── README.md
│       └── logs
│       	└── README.md
│       └── start
│       	└── README.md
│       └── searchSelect // 第一个组件API文档
│       	└── README.md
│   └── standard
│       └── css
│       	└── README.md
│       └── eslint
│       	└── README.md
│       └── js
│       	└── README.md
│       └── vue
│       	└── README.md
└── package.json

重启项目查看当前效果：

vuepress 实时显示组件效果 vuepress插件开发,vuepress 实时显示组件效果 vuepress插件开发_Vue_03,第3张

到此为止，纯的md文档已经完成，下面是需要将我们的组件显示在文档中。

组件API文档

文档其实还是和上面的README.md的书写差不多，只是路径修改了一下而已，最主要的不同其实是这里的文档中我们需要插入代码、显示我们的组件出来的效果，这里以wui-top-menu组件为例：
（注：这里时隔几个月以后再一次搭建了一个vuepress后对博客进行了二次编辑，希望出一个更详细的博客，所有有些文件名和内容跟上面创建的文件里的有些不同，理解精髓理解精髓）

具体查看README.md内容

// docs/ns-ui/wui-top-menu/README.md
<common-code-format>
  <div slot="componentNameTitle" class="component">
    <header class="component-name">wui-top-menu 头部导航</header>
  </div>

  <div slot="description">
    <header class="wui-description-title">基础用法</header>
  </div>

  <div slot="showComponents" class="wui-show-component">
    <top-menu-demo></top-menu-demo>
  </div>

  <highlight-code class="codeStyle" slot="showCode" lang="vue">
    <template>
      <wui-top-menu :menuData="menuData" />
    </template>
  </highlight-code>
  
  <highlight-code class="codeStyle" slot="showCode" lang="js">
    export default {
      data () {
        return {
          menuData: [
            {
              id: 370,
              label: 'WAF',
              url: '',
              children: [
                {
                  id: 458,
                  label: '策略管理',
                  url: '',
                  children: [
                    {
                      id: 469,
                      label: '频道管理',
                      url: '/channelManagement/channel/home'
                    },
                    {
                      id: 468,
                      label: '策略配置',
                      url: '/channelManagement/channel/config'
                    }
                  ]
                },
                {
                  id: 440,
                  label: '白名单配置',
                  url: '',
                  children: [
                    {
                      id: 455,
                      label: '通用配置',
                      url: '/whitelist/configure/home'
                    }
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  </highlight-code>
</common-code-format>

<common-api-format>
  <thead slot="form-header" class="formHead">
    <tr class="formHeadRow">
      <th class="formHeadCol">参数</th>
      <th class="formHeadCol">说明</th>
      <th class="formHeadCol">类型</th>
      <th class="formHeadCol">可选值</th>
      <th class="formHeadCol">默认值</th>
    </tr>
  </thead>
  <tbody slot="form-body" class="formBody">
    <tr class="formBodyRow">
      <td class="formBodyCol">menuData</td>
      <td class="formBodyCol">菜单数据</td>
      <td class="formBodyCol">Array</td>
      <td class="formBodyCol">—</td>
      <td class="formBodyCol">—</td>
    </tr>
  </tbody>
</common-api-format>

其中我们看到标签<common-code-format>，在vuepress中，在.vuepress/components/下新建的内容会自动注册为全局的组件，不用引入可以直接使用，对应的插槽中插入的内容都有对应的样式渲染。具体内容如下：

vuepress 实时显示组件效果 vuepress插件开发,vuepress 实时显示组件效果 vuepress插件开发_vuepress 实时显示组件效果_04,第4张

上面的插槽slot="showComponents"我们可以看到我们直接使用了一个全局标签，也是同样的道理，我们也要在.vuepress/components/中注册我们的全局组件，like this:

vuepress 实时显示组件效果 vuepress插件开发,vuepress 实时显示组件效果 vuepress插件开发_Vue_05,第5张

这里就将<wui-top-menu>注册为了全局组件供README.md文件使用了。

我们看下效果

vuepress 实时显示组件效果 vuepress插件开发,vuepress 实时显示组件效果 vuepress插件开发_Vue_06,第6张

对了，关于API中代码的高亮，以及我们是基于element-ui的二次开发，我们需要引入这些依赖，在docs/.vuepress/下新建enhanceApp.js文件（开头代码也展示过，这里说明下）：

// /.vuepress/enhanceApp.js
import VueHighlightJS from 'vue-highlight.js'
import 'highlight.js/styles/dark.css'
import ElementUI from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css'

export default ({
  Vue,
}) => {
  Vue.use(VueHighlightJS),
  Vue.use(ElementUI)
}

别忘了安装对应的依赖

npm i element-ui
npm i highlight.js
npm i vue-highlight.js
npm i sass-loader --save-dev
npm i node-sass --save-dev

关于我们的组件库中单个组件的文件结构可以看下图：

vuepress 实时显示组件效果 vuepress插件开发,vuepress 实时显示组件效果 vuepress插件开发_Vue_07,第7张

这里我们先不install组件，目前为止我们只是在本项目中利用相对路径访问，还未用到Vue的组件注册。

发布组件库

下面我们需要将我们的Wui里面的组件发布出去，我们的Wui像element-ui一样包含很多我们的业务组件。这里我们就需要涉及到Vue组件的全局注册以及发布了。
我们想要发布的是Wui，我们先进入到Wui目录下，然后，参考前一篇博客

坑

没有高亮

如果你按照以上步骤执行和安装后发现你的文档中的代码没有高亮效果，检查一下你的依赖版本"vue-highlight.js": "^2.2.0"，如果你的vue-highlight.js版本不是这个，你可以降一下版本然后再运行看看。我后期再写这个的时候安装了一个3.x的版本就没有高亮效果，也没有找到有效的解决方法，所以暂时就用2.2.0版本的就可以达到我们想要的效果。如果有使用最新版本解决高亮效果的麻烦留言告我一下，谢谢。

查看全文

https://www.xamrdz.com/lan/5gt1939464.html

vuepress编写API文档

介绍

搭建

安装

初始化

配置

组件API文档

发布组件库

坑

没有高亮

相关文章：