vuepresss搞一个类似elememt ui那样的组件库文档

创建文件夹并初始化

新建文件 zz-vuepresss

进到 zz-vuepresss

1. 初始化项目

 npm init -y

1. 安装 VuePress 为本地依赖

npm install vuepress -D

1. 根目录下创建 docs 文件夹并在内部创建 README.md 文件

看看我的 zz-vuepresss

1. package.json 添加运行脚本以及打包脚本。

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

1. 运行 npm run dev看看结果吧

基本配置

在文档目录下创建一个 .vuepress 的文件夹，所有 VuePress 相关的文件都将会被放在这里。你的项目结构可能是这样：

├─ docs
│  ├─ README.md
│  └─ .vuepress
└─ package.json

在 .vuepress 中创建 config.js 这是 VuePress 中必备的配置文件。应该导出一个对象，内容如下：

module.exports = {
  title: 'zz-vuepress',
  description: 'zz 组件库文档。'
}

导航栏

导航栏配置主要就两种方式，一级导航和下拉列表导航。修改 config.js。

module.exports = {
    title: 'zz-vuepress',
    description: 'zz 组件库文档。',
    themeConfig: {
        nav: [
            // 一级导航
            {text: '指南', link: '/guide/'},
            // 下拉列表导航
            {
                text: '了解更多',
                items: [
                    {text: 'github', link: 'www.baidu.com', target: '_blank'},
                    {text: 'preview', link: 'www.jingdong.com', target: '_blank'}
                ]
            }
        ]
        // 禁用导航，与上面的配置是互斥行为。
        // navbar: false
    }
}

经过上面的配置相信会有一些小伙伴点击了 “ 指南 ” ，发现 404 了。主要是 /guide/ 我们并没有配置，而 VuePress 遵循 约定优于配置 的原则。我们需要新建一个 guide 目录。

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

侧边栏

想要使 侧边栏生效，需要配置 themeConfig.sidebar，基本的配置，需要一个包含了多个链接的数组：

总体来说侧边栏大致分为两大类，一种根据标题生成，一种根据配置生成。根据配置生成的方式比较灵活，强烈建议反复查阅文档。

配置生成侧边栏

1. 首先在 guide 中创建 Button.md Card.md 文件。

.
├─ docs
│   ├── README.md
|   ├── .vuepress
│       └──  config.js
│   ├── guide
│   │   └── README.md
│   │   └── Button.md
│   │   └── Card.md
└─ package.json

1. 修改 config.js 文件

module.exports = {
    title: 'zz-vuepress',
    description: 'zz 组件库文档。',
    themeConfig: {
        nav: [
            // 一级导航
            {text: '指南', link: '/guide/'},
            // 下拉列表导航
            {
                text: '了解更多',
                items: [
                    {text: 'github', link: 'www.baidu.com', target: '_blank'},
                    {text: 'preview', link: 'www.jingdong.com', target: '_blank'}
                ]
            }
        ],
        // 禁用导航，与上面的配置是互斥行为。
        // navbar: false
        sidebar: {
            '/guide/': [
                ['', '介绍'], // '' 等价于 /guide/
                {
                    title: '组件',
                    collapsable: false,
                    children: [
                        ['../guide/Button.md', 'Button 按钮'],
                        ['../guide/Card.md', 'Card 卡片']
                    ]
                }
            ]
        }
    }
}

首页

经过上面的折腾，至此我们的 guide 相关的侧边栏，导航栏都已经完成了。紧接着就搞一个和 VuePress 一样的首页吧。

默认主题的首页是提供了一套默认的配置。 但是需要注意使用的前提。

• 根级的 README.md 中存在。
• home: true 是必须的。

---
home: true
heroImage: /img/avatar.jpeg   # 注意这里可以使外链，也可以是静态资源
heroText: Hero 标题
tagline: Hero 副标题
actionText: 快速上手 →
actionLink: /guide/  # 这里是点击快速上手后的跳转链接。
features:
- title: 简洁至上
  details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
- title: Vue驱动
  details: 享受 Vue + webpack 的开发体验，在 Markdown 中使用 Vue 组件，同时可以使用 Vue 来开发自定义主题。
- title: 高性能
  details: VuePress 为每个页面预渲染生成静态的 HTML，同时在页面被加载的时候，将作为 SPA 运行。
footer: MIT Licensed | Copyright © 2018-present Evan You
---

注意上面的图片存放位置

默认是在 .vuepress -> public 防止以后图片过多我分了一个文件夹.vuepress -> public -> img

赶快从新运行你的项目你会看到如下结果

好看吧

这些是基本的配置了，接下里才是我们的重头戏

markdown 语法拓展

文件导入之前我们需要了解一个小知识：

• docs/.vuepress/components 该目录中的 Vue 组件将会被自动注册为全局组件。换句话说就是在这个文件夹中的 *.vue 是可以在 *.md 中当做组件被使用的。

components/demo-1.vue` 在使用时则是 `<demo-1></demo-1>
components/guide/demo1.vue` 在使用时则是 `<guide-demo1></guide-demo1>

• *.md 中也是会支持 Vue 的模板语法。原因是：Markdown 文件将首先被编译成 HTML，接着作为一个 Vue 组件传入 vue-loader

这意味着你可能会写出以下代码。

看一下我们的组件

新建 docs/.vuepress/components/demo-1.vue

<template>
  <div>
    <h2>我是自定义的组件哦</h2>
  </div>
</template>

新建文件 docs/.vuepress/components/zz/demo.vue

<template>
  <div>
    <h3>我还是组件{{msg}}</h3>
  </div>
</template>
​
<script>
export default {
  data() {
    return {
      msg: 'Welcome to scalable'
    }
  },
}
</script>

然后在 你想用的地方这样用就行了

<zz-demo />
<demo-1 />

注意需要重启一下

引入外部组件（应用级别配置）

官方： 由于 VuePress 是一个标准的 Vue 应用，你可以通过创建一个 .vuepress/enhanceApp.js文件来做一些应用级别的配置，当该文件存在的时候，会被导入到应用内部。enhanceApp.js 应该 export default一个钩子函数，并接受一个包含了一些应用级别属性的对象作为参数。你可以使用这个钩子来安装一些附加的 Vue 插件、注册全局组件，或者增加额外的路由钩子等。

// 使用异步函数也是可以的
export default ({
  Vue, // VuePress 正在使用的 Vue 构造函数
  options, // 附加到根实例的一些选项
  router, // 当前应用的路由实例
  siteData, // 站点元数据
  isServer // 当前应用配置是处于 服务端渲染 或 客户端
}) => {
  // ...做一些其他的应用级别的优化
}

上面的内容告诉我们可以使用插件，这是写组件库文档必不可少的，刚好符合需求，接下来就按照官方的提示改造 enhanceApp.js ：

文档就用 element-ui 作为示例

新建文件 docs/.vuepress/enhanceApp.js

import ElementUI from 'element-ui';
import 'element-ui/lib/theme-chalk/index.css';
​
export default ({ Vue, options, router, siteData, isServer }) => {
  Vue.use(ElementUI);
};
​

安装 element

npm install element-ui

安装Demo插件

这里我们会使用到一个 vuepress-plugin-demo-container 这个插件，使用以下命令安装

npm install vuepress-plugin-demo-container

然后在/docs/.vuepress/config.js文件中配置上该插件

module.exports = {
  // ...
  plugins: ['demo-container'], // 配置插件
  markdown: {}
}

修改Button.md

::: demo 适用广泛的基础单选
```html
<template>
  <el-select v-model="value" placeholder="请选择">
    <el-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value">
    </el-option>
  </el-select>
</template>
​
<script>
  export default {
    data() {
      return {
        options: [{
          value: '选项1',
          label: '黄金糕'
        }, {
          value: '选项2',
          label: '双皮奶'
        }],
        value: ''
      }
    }
  }
</script>
```
:::

看页面，哈哈没效果，找了半天原因，大概率是我的vuepress的版本太低导致的，所以从新装一下

npm install vuepress

然后重启，成功啦

还有一个问题，我这边复制了 el-button，但是默认样式可不是这样的，修改页面的默认样式

新建docs.vuepress\styles\index.styl

/*我们就直接写css了,默认是stylus格式的*/
​
.el-row{
  margin-bottom:12px;
}
​

最后我们build一下,看会不会报错

npm run build

成功啦。

参考链接：

报错解决

你没有任何义务做一年前，一天前，甚至15分钟前的那个自己。无需抱歉 忐忑 愧疚，你天生拥有经历 变化 以及成长的权利。