使用vuepress创建第一个组件说明文档

背景

前面我们学习了如何给项目配置vuepress，下面我们可以来学习创建自己的第一个组件说明文档了

创建第一个组件md

比如我们有一个数字输入框xl-number-input组件
首先，我们现在docs文件夹下新建一个numberInput.md文件，我们在文档上面看到的说明内容，其实就是这个md文件，这时候我们会发现，左侧的导航是/component/numberInput，而不是中文名称，那我们怎么设置呢？其实md文件夹中，第一行定义的标题会自动变成我们左侧导航栏的名称，所以我们的md文件这样写

# numberInput数字输入框
常规的数字输入框

对应左侧导航就会从component/numberInput转变为numberInput数字输入框了，这个地方挺坑的
然后我们观察别人的组件文档，是可以直接展示组件demo的，这个地方就需要使用固定写法了，以下两种写法都可以

<number-input-base></number-input-base>
### 基础用法
<ClientOnly>
  <number-input-base></number-input-base>
</ClientOnly>
```vue
<template>
  <xl-number-input v-model="input"></xl-number-input>
</template>
<script>
  export default {
    data() {
        return {
            input: ''
        }
    }
  }
</script>
``

vuepress解析的时候会自动帮你解析成你的组件，第二种写法套了一个ClientOnly标签，官方的解释是说，对于我们组件库我没有研究出特别的，可以再仔细看看

如果你正在使用，或者需要展示一个对于 SSR 不怎么友好的组件（比如包含了自定义指令），你可以将它们包裹在内置的 组件中

截图展示如下：

看截图是直接把我们的numberInput渲染出来了，那这标签是如何渲染出来的呢？这个地方就是我感觉用vuepress比较麻烦的地方了，以后可以用gulp进行自动化写入

<number-input-base></number-input-base>

第一步：

• markdown解析到上面字段时，其实是从docs文件夹下，找到.vuepress文件夹，然后在下面的components文件夹中寻求匹配项，所以我们首先需要根据这个路径建立components文件夹

第二步：

• components文件夹下面，你需要给我们的每一个组件单独建立一个文件夹，这个文件夹下面，可以放多个demo，我们的文档中想要直接展示可执行的vue组件，其实就是在执行这些demo，这个demo里面可以引入你已经写好的组件，类似于我们写好组件后的example文件，为的就是进行例子展示

• 这个文件夹下面，放多个demo，因为我们的组件可能会有不同属性的展示形式，比如说这个numberInput，一个demo是展示默认选项内容，一个是拿来展示两个数字的情况，或者是拿来展示disabled的情况，这就是三种情况，也就是三个demo

第三步：

• 在numberInput文件夹下面新建base.vue文件，表示这是一个默认的numberInput（假设我们的numberInput组件不依赖第三方库） ```javascript

``` 以上就可以在启动命令在浏览器中看到我们想要的效果了
下面，我们来分析以下，md文件中的标签名字是怎么回事？？
可以看到我们在md中使用了标签，md是这么解析的

1. 标签被拆分成三个，number、input、base
2. 在components文件夹下面找number文件夹，如果有，则在number文件夹下找input文件夹，如果也有，就会在input文件夹下面找base.vue文件
3. 如果有number文件夹没有input文件夹，则会找input-base.vue
4. 如果没有number文件夹，则会找number-input-base.vue文件

很明显，以上步骤都找不到我们的文件，但是以此类推，我们的标签会在components文件夹下找到number-input文件夹，然后再找到base.vue文件，所以说，md中写的标签名称，实际上是跟我们components中demo组件的name属性无关，也跟我们md文件名字无关