写点什么

解析 Markdown 文件生成 React 组件文档

  • 2021 年 11 月 12 日
  • 本文字数:2359 字

    阅读完需:约 8 分钟

这个方案并不是我凭空想象出来的,而是在前公司中就有这么一个内部应用,组件开发人员自己编写 markdown 文件,最终生成组件文档,并且应用本身可以解析 markdown 文件中的代码部分,从而在组件文档中生成对应的组件示例。


彼时我只是一个组件开发人员,并不是这个文档应用的实现人员,所以也不知道其技术原理。


但是前公司这个应用让我知道了这么玩行得通,当时作为组件开发人员,接受和使用这个应用异常轻松,只要会写 markdown 就行了,没有学习成本。而且使用这种方式,控制权掌握在自己手中,更容易和自己的团队项目有效结合起来。


基本原理




虽然这个文档应用是我一个人花了两天的时间独立完成,但是花的是工作时间,完成后也是公司内部项目,所以这个文档应用我没法开源出来。


不过我可以告诉大家一个主要思路和步骤,想必复现出来也并不困难。


第一步让我们搞定这个项目的框架。


因为需要引入 single-spa 的 utility 应用,所以框架我直接用的是 single-spa 的基座,并且项目内含一个子应用用于展示文档。而 utility 应用直接引入线上开发环境的 utility 应用,避免团队成员重复书写组件代码,也解决了文档和实际应用不同步的问题。


通过这一步,我们解决了 StoryBook 方案中的痛点 2 和痛点 3。


第二步我们需要载入 markdown 文件。


这一步肯定是通过 webpack 的加载器来做处理,这些加载器有的比较强大,可以直接将 markdown 文件转换为 html。但是我并没有选择这种,而是直接用的 raw-loader,将我们的 markdown 文件转换为字符串载入。


代码大致如下,这个比较简单,就不说了。


module.exports = {


module: {


rules: [


{


test: /.md$/,


use: 'raw-loader'


}


]


}


}


第三步我们需要解析 markdown 文件生成文档,并解析其中的 React 组件,生成组件示例。


解析 markdown 文件转换为 html 文档,实际上有个比较强大的库,叫Showdown


而我所用到的库react-showdown则是对 Showdown 的进一步封装,可以借助一个 react 组件将 markdown 和包含在 markdown 文件中的 react 组件渲染成 html。


下面是它的一个官方示例:


import React from 'react';


import MarkdownView from 'react-showdown';


export default function App() {


const markdown = `

Welcome to React Showdown :+1:

To get started, edit the markdown in `example/src/App.tsx`.


| Column 1 | Column 2 |


|----------|----------|


| A1 | B1 |


| A2 | B2 |


`;


return (


<MarkdownView


markdown={markdown}


options={{ tables: true, emoji: true }}


/>


);


};


通过 MarkdownView 这个组件,可以将一串 markdown 格式的文本转化为 html。


另外我们注意到它的选项,tables 为 true,如果不设置这个的话,markdown 中的 table 格式将不会被转化成表格。第二个 emoji 为 true 是支持 emoji 转换。


这个时候你可能要问,这只是转换了一下 markdown 文件而已,转换 react 组件呢?


我们可以看一下下面这个官方示例:


import MarkdownView from 'react-showdown';


function CustomComponent({ name }: { name: string }) {


return <span>Hello {name}!</sp


【一线大厂Java面试题解析+后端开发学习笔记+最新架构讲解视频+实战项目源码讲义】
浏览器打开:qq.cn.hn/FTf 免费领取
复制代码


an>;


}


const markdown = `

我是个标题:

<CustomComponent name="world" />`;


<MarkdownView markdown={markdown} components={{ CustomComponent }} />


在 markdown 文本中可以直接写上 CustomComponent 这个自定义的 react 组件代码,然后在 MarkdownView 的 components 中传入 CustomComponent 即可。


生成的最终 html 中不仅会有个标题,标题下面还会展示一个叫**hello world!的文本,而不是展示<CustomComponent name="world" />**这个字符串。


排疑解难




看完了上面的原理,想必您已经可以实现这样的一个文档应用了。


不过在这个过程中您可能还是会遇到一些小麻烦,这里提前给您支个招。


麻烦 1:markdown 转换成 html 后的代码高亮处理。


因为我们做的是一个组件文档,那么肯定会涉及到代码展示。


markdown 文件中的代码块,使用 react-showndown 转换后的并没有做高亮处理。


不过 react-showdown 是支持 Showdown 的各种扩展的,其中有个扩展叫 showdown-highlight,通过这个扩展可以对代码块做高亮处理。


麻烦 2react-showndown 只支持简单的组件。


虽然 react-showndown 可以解析 react 组件代码,但是它也只能简单解析这个组件。如果我们演示的示例比较复杂,涉及到一些函数,还有一些库的引用,很显然不能再 markdown 文件中直接写。


这里我建议直接将每个组件的示例写到一个独立的 js 中,这个 js 导出一个 Demo 组件,然后我们在 markdown 文件中直接引用这个 demo 组件即可。


大致代码如下:


import MarkdownView from 'react-showdown';


import ButtonDemo from './ButtonDemo';


const markdown = `

按钮组件

组件描述

代码示例

<ButtonDemo />


这里贴出以 ButtonDemo 组件中的代码

API

| 属性 | 说明 |XXX|


|----------|----------|-----|


| title | 按钮文本 | XXX |


| type | 按钮类型 | XXX |


`;


<MarkdownView markdown={markdown} components={{ ButtonDemo }} />


通过上面这种方式,不论我们 ButtonDemo 中的逻辑和功能多么复杂,展示出来都是没问题的。


麻烦 3:如何将这个文档应用做到简单好用。


看了上面的代码,可能有人会觉得应该没问题了。


但是我们得明白,我们这个东西是做给业务开发的人员用的,而不是做给我们自己用的。


我业务开发人员为什么要知道你这些什么 react-showdown 的代码?


我业务开发人员还要学习你的这些鬼东西?


不是每个人都想着学这些乱七八糟的技术好吗?


我每天就只想在 6 点下班,就算你 5 分钟内给我讲明白了,你这个文档应用我用不用还两说。


你要是 5 分钟之内还讲不明白怎么用,那你休想我在这上面给一个公共组件写文档。


我们面对的基本就是这么一个场景,我们做这个应用是为了解决项目中实际面临的问题,是面向业务开发人员编程,而不是面向领导和 KPI 编程。

评论

发布
暂无评论
解析Markdown文件生成React组件文档