前言

每每开发完一个组件后，我都会去公司的wiki上写相关的api描述文档，在经过一段时间的开发后，实在是忍受不了纯文本的组件文档了。我对于element-ui、ant design官网这种可以交互的文档垂涎不已，如果在他们的基础上再加上两个功能：

1.掘金这种markdown在线编辑的功能
2.真实可靠的组件使用源码(至少ant design文档上组件查看代码，并不是真实的源码，巨坑)

开整

第一步：确定文档格式

类比element-ui、ant design，每个组件都有多个展示模块，每个模块都由文本、可交互的组件渲染结果、该组件的源码,如图

这里我就直接把布局设计抄了过来

第二步：文本部分要实现成`markdown`在线编辑

这里过程细节就不描述了，反正费了一些心思，233333333
首先markdown编辑器肯定就不需要我自己实现了，直接采用v-md-editor 下面是部分伪代码

<div class="component_mark">
      <div>
        <EditorMarkDown :markDownName="markDownName" @change="$emit('change')" />
      </div>
      <section class="compoent_mark_body" v-if="markType === 'module'">
        <div class="tool_bar">
          <div class="tool_bar_item">
              <a-tooltip title="复制代码" arrow-point-at-center>
                <span class="copy_code tool_icon" @click="copyBtn"> <CopyFilled /></span>
              </a-tooltip>
            </div>
            <div class="tool_bar_item">
              <a-tooltip title="查看代码" arrow-point-at-center>
                <span class="show_code tool_icon" @click="showCodeBtn"><LeftOutlined /><RightOutlined /></span>
              </a-tooltip>
            </div>
        </div>
        <div class="show_component">
            <slot></slot>
        </div>
        <div class="code_body" ref="showCodeRef">
            <v-md-preview ref="previewRef" :text="codeVal"></v-md-preview>
        </div>
      </section>
    </div>

最终实现成果如下

第三步：数据如何持久化

作为自发的自研项目，公司的后端同学自然是不会支持我啦。就算我自己写后端，我也没权限连上公司服务器，就更别说数据库了。所以最终采用nodejs结合本地文件存储的方式完成。由于我用的是vue cli，然后在项目内部加一个express服务，（不要问我为啥不用nuxt,因为可以，但没必要....）。在启动vue服务时，一并启动express，部分代码如下

"scripts": {
    "serve": "concurrently \"node src/server/start.js\" \"vue-cli-service serve\""
    }

这种存储方式有一个好处是我之前没有预料到的，那就是文档内容可以跟随git分支走，由不同分支的存储文件不同，所以可以很好的控制组件文档跟着组件库版本分支走。

第四步：本地开发模式与线上模式区分

主要是只有在本地开发模式下才可以编辑markdwon。打包上线后，正式环境下，是不可能再提供编辑功能的。
所以我也只会在本地开发模式下开启express。正式环境则从打包时生成的离线文件种读取文档信息。
大致原理就是，
本地开发模式下：1.会实时读取存储markdwon数据；2.实时读取组件源码
打包时: 先生成上面两种离线文件，然后再进行打包
正式环境：读取上面两种离线文件

第五步：如何让开发人员更专注于文档编辑

即使依然有很多细节没有讲，从上面介绍的几点来看，你可能会认为想写一个文档并不轻松，的确，如果不做自动化处理的话，那是相当费力的。所以我在系统中做了大量的自动化处理，所以几乎你只需要做引入组件，配置路由，然后在线编辑文档就可以了

这是在线演示地址（线上是不支持在线编辑的，只有在本地开发模式下运行才会有编辑按钮）

点我点我点我（点击左上角“我想维护该文档可以看我录的演示视频”）

缺点：无法支持跨框架，比如该系统是用vue3写的，那么就解析不了用react封装的组件。

关于这个问题，据说有一些框架是支持跨框架的，这个有兴趣的朋友可以研究下，本社畜最近工作太多了....

源码地址:

点我点我点我

npm组件库开发之组件文档篇

前言

开整