遗留问题
书接上回，说道利用 sideEffects 字段，只需读取源文件即可实现按需加载，还有个坑忘了说...
文档中的样式打包后会丢失...
因为我们只注意到了作为组件库的源代码，而忘了我们的文档是通过 vuepress 编译，即底层也是基于 webpack 进行打包。所以 sideEffects 中也要加上文档中的文件。
组件文档该写些什么？
在编写组件库文档时，有两个必不可少的部分。
- 组件预览，最好有相应的代码
- 组件 api，即 props、events、slots 等接口和参数的说明
如何同时展示 demo 和 code？
- 最【一力降十会】的方法当然就是复制粘贴一把梭...
这样实现简单是简单，不过维护时要同时改至少两份代码。比如 vant 的展示文档 和 cube-ui 的展示文档。
- 进阶一点儿的方法就是嵌入
Codepen、JSFiddle或CodeSandbox的iframe。
但是组件库中一般有大量的组件，不可能为每个组件都维护一份小代码片段，并且别忘了这可是三个平台（硬点一个吼不吼啊~？）。
- 因此各种组件库使用的最多的方法还是自己编写组件。（下一小节详解）
- 当然也有例外比如 vux 只有 demo 没有 code。
业界的文档组件
-
最普遍的方式还是基于
markdown-it，将自己的 vue 组件插入文档中。 -
比较有意思的是 mand-mobile 的文档编写方式。demo 的文档放在组件目录中，然后由
Doc组件读取各个组件的 demo。 - 那么对于我们使用 vuepress 编写文档的开发者来说咋办咧？
在 vuepress 中展示 demo 和 code
首先让我们来分析一下：这两份重复的代码应该以谁为主？即我们应该只编写 demo 的代码还是 code 的代码？先有鸡还是先有蛋？物质决定意识还是意识决定物质？
至少在编写 demo 和 code 这个问题中，我认为 demo 才是“本源”，为什么？
- 这是最普遍的方式，各大组件库基本这么干
- 这是最自然的方式，因为 vuepress 会编译 md 中的 vue 组件
-
若是反过来，文档中以 code 为主，再由 code 生成 demo 会有一些不便
- 如何预处理代码：babel、scss 等？
- 如何插入生成的组件到文档中？
- 感兴趣的话可以看看这个插件 vuepress-plugin-demo-block
一开始我只在 .vuepress/components/ 中建了个组件自娱自乐，后来看到了 vuepress-plugin-demo-block，但觉得由 code 生成 demo 有点儿绕。
于是自己搞了个插件 vuepress-plugin-demo-code，有需要的读者老爷可以自取~
组件的 api 文档
解决了 demo 和 code 的重复编写问题，接下来是另一个令人无发可脱的问题：如何自动生成并同步 .vue 组件的 api 文档？
手动维护肯定是不行的，还好有一个炒鸡好用的库 vuese。vuese 会基于 ast 分析你的 .vue 文件，提取其中的 props、events、slots 等接口和参数的说明。
为了将其集成到 vuepress 中，我又整了个 markdown-it 插件 markdown-it-vuese。
只需使用以下的语法在导入已经存在的 *.vue 文件的同时，使用 Vuese 自动生成文档。
<[vuese](@/filePath)以上 to be continued...
参考资料
- muse-ui 的 demo-block 组件
- muse-ui 的 markdown-it 配置
- ant-design-vue 的 demoBox 组件
- ant-design-vue 的 markdown-it 配置
- element 的 demo-Block 组件
- element 的 markdown-it 配置
- vux 的展示文档
- vant 的展示文档
- cube-ui 的展示文档
- mand-mobile 的展示文档
- mand-mobile 的 Doc 组件
- vuepress-plugin-demo-code
- vuepress-plugin-demo-block
- vuese
- markdown-it-vuese
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用。你还可以使用@来通知其他用户。