痛点

写过react库的同学都清楚,需要提供库源代码、用于测试库代码的测试用例、文档。其中文档归文档,文字加图片。想要看实际的运行效果,还需把库跑起来看实际效果。 同时库和文档的同步维护难,经常是库改了,增加了某些功能,文档还是旧的。

大家都是程序员,要写一份高质量文档,呵呵呵呵。

期望

用Markdown提供一份直观的React文档,有可运行的示例,有示例源代码,有示例的说明。这样用户看起来直观,编写者写起来也直观,维护成本低。比如element,只是基于vue的。github搜了下,貌似没找到相关的轮子。

于是经过几番尝试,结合 React 的特点。写了一套处理 Markdown 文件的 webpack loader,可以将 Markdown 转成 React 文件。

这份readme.md对应的效果是doc。 还有我们的库react-gm 对应的文档是docps:初期没优化,react打包出来文件大,加载略慢,and用chrome

原理

无论es6es5,还是md转react component,对于webpack来说无非就一种字符串转成可执行的js而已。

所以md转react component说白了就是一种转换规则: md -> html -> react component -> 网页。

同时对示例部分把示例代码copy一份,当成实际能执行的用例,在添加点说明。这样一来就有可运行的示例,有示例源代码,有示例的说明。且测试用例和文档只对应一份md,天然合一。

大致思路如下:

clipboard.png

更多详细的介绍在这里markdown-it-react-loader

本文固定链接: http://www.js-code.com/react/react_42315.html