如何优雅的使用Vuepress编写组件示例（上）👈

这是我参与8月更文挑战的第1天，活动详情查看：8月更文挑战

前言✍️

最近在搭自己的组件库，关于文档用的是Vuepress
官网在文档说明展示组件示例的方法有很多种，但种种都不合心意
通过查阅网上的资料和Element的源码找出了我认为的一种最优解，借此机会分享一下
该篇主要是对思路的分析和归纳，如果想直接看具体操作可以看到如何优雅的使用Vuepress编写组件示例（下）

实际效果✔️

先把最后的成品发出来给大家看看

优化前
优化后

可能对于效果没什么区别但是把markdown代码放出来就差别很大了

可以看到，页面不仅美观了些许，代码可以说是非常简洁了，具体是怎么做到的呢，请听我细细道来

开始动手✊

文档选择

对于一个组件库来说，有一个合适的文档来展示组件demo是最最基本的事情，由此我选择了Vuepress是觉得简洁大方
Vuepress的诞生初衷是为了支持Vue及其子项目的文档需求所以他的风格跟Vue的文档很像

着手展示

在Vuepress中，本来就支持在markdown文件中编写符合Vue语法的代码
Vuepress内部将markdown语法转化成vue进而通过内部集成的vue-loader来得到最终的HTML
所以我们在.md文件中既可以输入md语法也可以输入Vue代码，这么一来就好办了啊(狗头)

啪！很快啊，不管三七二十一直接把自己的组件写上去了，虽然有点麻烦但最终效果还是我想呈现的那样(此时我还没发现事情的严重性)

感觉麻烦

当我写到第二个组件示例的时候，感觉事情有点不对了
在我用上面那种方法来呈现demo的时候发现这种方法有很大的问题

样式编写麻烦对于文档组件例子的样式基本是都一样的都是一个框下面一个代码，但是用了上面那种呈现方式每次样式要重新写(再加上md文件没有代码提示太难受)
代码重复 由上图可知我写一个button的示例同样的代码写了两遍分别用于展示demo和展示代码
页面杂乱 由上图可知在一个md文件里又有md语法又有vue语法实在是混乱
没有集中管理 每一个例子按理说都有一个通用的东西（例如样式）没有集中管理，一改就要全部改

重新选择

第一种方法🙅‍♂️

上文所述直接在md文件编写Vue+md的语法(淘汰！ 这种方法要复用的代码太多不方便)

第二种方法🙅‍♂️

每个demo封装一个vue组件分开维护，通过Vuepress直接渲染的方式呈现，样式也统一在一个css里面导入进去，但是这种方法还是使文档存在组件的语法，页面多起来会很不好维护

# Button 按钮
<btn></btn>

## 使用
```html
<l-button>默认按钮</l-button>
<l-button type="primary">主色按钮</l-button>
<l-button type="success">成功按钮</l-button>
<l-button type="info">提示按钮</l-button>
<l-button type="warning">警告按钮</l-button>
<l-button type="danger">错误按钮</l-button>
```

第三种方法🙅‍♂️

在上面的基础上通过Vuepress自带的<<< @/filepath导入代码块

## Button 按钮
<btn></btn>
## 使用
```html
<<< @/docs/.vuepress/components/btn.vue
`` `

在尝试了上面三种方法之后还是觉得我不仅要在组件里面写代码还要在md文件也要写，还是觉得有点麻烦的，有没有更好的办法可以让我只在md文件编辑，页面就直接更改呢？
就在我快要想秃噜皮的时候瞄了一眼element的文档，看到这清一色统一的样式就在思考这些UI库都是怎么管理的呢
打开element的源码突然恍然大悟😋

第四种方法🙆‍♂️

真的是看一次企业级源码胜读十年书，怎么会有如此简便的写法，通过自定义容器来编辑，样式统一管理，文档干净简洁，就决定是他了！！🍧

### 禁用状态

按钮不可用状态。

:::demo 你可以使用`disabled`属性来定义按钮是否可用，它接受一个`Boolean`值。

```html
<el-row>
  <el-button disabled>默认按钮</el-button>
  <el-button type="primary" disabled>主要按钮</el-button>
  <el-button type="success" disabled>成功按钮</el-button>
  <el-button type="info" disabled>信息按钮</el-button>
  <el-button type="warning" disabled>警告按钮</el-button>
  <el-button type="danger" disabled>危险按钮</el-button>
</el-row>

<el-row>
  <el-button plain disabled>朴素按钮</el-button>
  <el-button type="primary" plain disabled>主要按钮</el-button>
  <el-button type="success" plain disabled>成功按钮</el-button>
  <el-button type="info" plain disabled>信息按钮</el-button>
  <el-button type="warning" plain disabled>警告按钮</el-button>
  <el-button type="danger" plain disabled>危险按钮</el-button>
</el-row>
```
:::

摸索摸索🧠

说实话刚打开element源码的时候还有点蒙不清楚这个:::demo是怎么来的
于是观察element文档发现通过这个自定义容器会自动编译成有demo-block类的组件

::: demo
xxx
:::

在源码搜索后找到对应的文件

接下来只要搞清楚他是怎么通过这句小小的代码编译转化成这个组件的就可以了
咦~编译？什么时候会有编译？webpack处理？！！！

{
        test: /\.md$/,
        use: [
          {
            loader: 'vue-loader',
            options: {
              compilerOptions: {
                preserveWhitespace: false
              }
            }
          },
          {
            loader: path.resolve(__dirname, './md-loader/index.js')
          }
        ]
      }

原来如此，从配置文件中可以看出，Markdown先经由md-loader处理，然后再交由vue-loader处理。经过这两个loader的处理，Markdown就与Vue组件一样了
虽然element用的不是Vuepress但底层都是关系到markdown，那是不是可以参考一下让我们的Vuepress也像element文档一样使用这个自定义容器呢？答案是可以的！！

李性分析🙋‍♂️

在看过element的源码后大概知道是怎么回事了

第一步构建一个通用组件用于接收代码块来展示demo并且统一样式
第二步设定一个Markdown自定义容器来编写demo代码
第三步把自定义容器转化成之前构建的通用组件，这样就可以在md使用自定义容器来实现上文效果
第四步扩展markdown渲染方法使我们输入的代码块可以输出内容为符合Vue Template语法的代码块
第五步变成了vue代码后交由Vuepress的vue-loader处理编译为文档

写在最后🐌

此篇主要缕了一下通过如何将md文件的自定义容器里代码块转化成vue组件并渲染，接下来我会分享一下我是如何在Vuepress使用的
防止文章太长影响体验，剩下的具体分析和操作放在如何优雅的使用Vuepress编写组件示例(下)
如果您觉得这篇文章有帮助到您的的话不妨🍉关注+点赞+收藏+评论+转发🍉支持一下哟~~😛

往期精彩🌅