工具

代码能够组件化，文档也可以，今天要介绍的是 remark，功能强大到你想不到。
image.png

The world’s most popular Markdown pars**er! ** 一点也不夸张，掌握了它，你可以为所欲为。

需求

最近在做 G2Plot V2（简称 G） 和 Ant Design Charts （简称 A，G2Plot React 版本），1.0 文档已经被诟病很久了，2.0 我们决定在文档上下手，尽扯淡，进入正题，大家都知道，每个图表都有很多通用属性，例如 width 、height 等等，如果给每个图表都CV一遍，成本也是很高的毕竟好几十个图表，而且不方便维护，作为前端开发，最先想到的当然是组件化了。

组件化

提取公用文档到指定目录，每个图表通过特殊标识引入即可，公用文件里面可以继续引入公用文件，层级不限。这不是就是个正则替换吗？当然，如果你正则足够牛逼，你也可以为所欲为。

源文件

为了方便演示，所有文件放统一scripts目录下。
#test.md

  1. ## 配置属性
  3. ### 图表容器
  5. `markdown:./common-a.md`

common-a.md

  1. #### width
  3. <description>**可选** _number_</description>
  5. 功能描述：设置图表宽度。
  7. 默认配置：`400`
  9. #### height
  11. <description>**可选** _number_</description>
  13. 功能描述：设置图表高度。
  15. 默认配置：`400`
  17. `markdown:./common-b.md`

common-b.md

  1. #### nice
  3. <description>**可选** _boolean_</description>
  5. 功能描述：是否美化。
  7. 默认配置：`true`
  9. #### min
  11. <description>**可选** _number_</description>
  13. 功能描述：坐标轴最小值。
  15. 默认配置：`无`

**

代码实现

执行入口，unified.js

  1. const fs = require('fs');
  2. const path = require('path');
  3. const remark = require('remark');
  4. const { mdprima } = require('./mdprima.js');
  6. // 文件路径，上层自动扫描
  7. const filePath = path.resolve(__dirname, './test.md');
  9. const res = remark().use(mdprima).processSync(fs.readFileSync(filePath));
  11. fs.writeFileSync(path.resolve(__dirname, './API.zh.md'), res.contents);

核心文件 mdprima.js

  1. const path = require('path');
  2. const fs = require('fs');
  3. const remark = require('remark');
  4. // js 示例转 React 语法，Ant Design Charts 层使用
  5. // const parseFile = require('./parse-v2.js');
  7. const mdprima = () => {
  8.   return function transformer(tree) {
  9.     recursionTree(tree);
  10.   };
  11.   function recursionTree(tree) {
  12.     // 删除顶部导航
  13.     if (tree.type === 'thematicBreak') {
  14.       tree.type = 'html';
  15.     }
  16.     // 解析套娃路径
  17.     if (tree.type === 'inlineCode' && tree.value.indexOf('markdown:') !== -1) {
  18.       const filePath = tree.value.split(':')[1];
  19.       const docsPath = path.resolve(__dirname, filePath);
  20.       const processor = remark().use(mdprima).processSync(fs.readFileSync(docsPath));
  21.       tree.type = 'html';
  22.       tree.value = processor.contents;
  23.     }
  25.     if (tree.children && tree.children.length) {
  26.       tree.children.forEach((children) => {
  27.         recursionTree(children);
  28.       });
  29.     }
  30.   }
  31. };
  33. module.exports = { mdprima };

终端执行 node scripts/unified.js 即可生成生成 scripts/API-zh.md 文件
#API-zh.md

  1. ## 配置属性
  3. ### 图表容器
  5. #### width
  7. <description>**可选** _number_</description>
  9. 功能描述：设置图表宽度。
  11. 默认配置：`400`
  13. #### height
  15. <description>**可选** _number_</description>
  17. 功能描述：设置图表高度。
  19. 默认配置：`400`
  21. #### nice
  23. <description>**可选** _boolean_</description>
  25. 功能描述：是否美化。
  27. 默认配置：`true`
  29. #### min
  31. <description>**可选** _number_</description>
  33. 功能描述：坐标轴最小值。
  35. 默认配置：`无`

总结

出于演示，只给了最简单的代码示例，真正用到项目中时，有很多问题需要去解决的，这些是正则难以处理的，大家有时间可以多研究哈 remark ，真的很强大。