解析Markdown文件生成React组件文档
前言
最近做的项目使用了微前端框架single-spa。
对于这类微前端框架而言,通常有个utility应用,也就是公共应用,里面是各个子应用之间可以共用的一些公共组件或者方法。
对于一个团队而言,项目中公共组件和方法的使用难点不在于封装不在于技术,很多时候在于团队内部成员是否都能了解这些组件,以避免重复开发,从而提升团队效率。
如果是团队比较小,人员比较稳定的项目组可能还好点,对于团队比较大,人员流动较快的团队,这些通用组件和方法往往就被人遗忘在角落,很难再得到有效利用。
因为我所在的项目还在开发初期,并且是新入职也想去熟悉一下当前项目中的一些通用组件和方法,所以我自己特意开发了一个文档应用去解决这个问题。
技术方案选型
对于一个面向Ant Design编程的咸鱼而言,这个文档应用肯定是往这个方向做。
目标是能做成Ant Design的组件文档那样好用,既能很快看清组件的使用效果,也能快速复制示例代码。
有了目标之后,很快选定了两个技术方案
- StoryBook方案
- 自己开发解析markdown文件的文档应用
StoryBook是市面上一款比较流行的构建UI组件和文档的库,功能很强大。
但是这个库如果要应用到我们项目的团队存在以下问题:
- 英文文档,有学习成本
- 引入single-spa的utility应用很麻烦
- 对于构建在utility应用中的组件,需要在StoryBook中再写一遍,容易不同步
- 对于通用方法可能不支持
尤其是第三点特别存在问题,团队成员大都是业务开发,有交付压力,不是在github上为爱发电的开源贡献者。
他们是否有意愿在utility应用中写了一遍组件代码后,又专门跑到这个StoryBook中再写一道?
如果组件代码修改后,StoryBook这边没修改,这种不同步很容易导致开发人员明明按照文档使用组件,但是组件就是报错,挫败感很强。
联系到现实,我已经预想到如果走这个方案,一个月内这个玩意就会名存实亡,成为形式主义的存在,在三个月后成为大家都不愿提起的垃圾了。
所以有了第二个方案的诞生:自己开发解析markdown文件的文档应用。
这个方案并不是我凭空想象出来的,而是在前公司中就有这么一个内部应用,组件开发人员自己编写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 (<MarkdownViewmarkdown={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}!</span>;
}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,通过这个扩展可以对代码块做高亮处理。
麻烦2:react-showndown只支持简单的组件。
虽然react-showndown可以解析react组件代码,但是它也只能简单解析这个组件。如果我们演示的示例比较复杂,涉及到一些函数,还有一些库的引用,很显然不能再markdown文件中直接写。
这里我建议直接将每个组件的示例写到一个独立的js中,这个js导出一个Demo组件,然后我们在markdown文件中直接引用这个demo组件即可。
大致代码如下:
import MarkdownView from 'react-showdown';
import ButtonDemo from './ButtonDemo';const markdown = `
# 按钮组件组件描述## 代码示例<ButtonDemo />```tsx
这里贴出以ButtonDemo组件中的代码
```## API| 属性 | 说明 |XXX|
|----------|----------|-----|
| title | 按钮文本 | XXX |
| type | 按钮类型 | XXX |`;<MarkdownView markdown={markdown} components={{ ButtonDemo }} />
通过上面这种方式,不论我们ButtonDemo中的逻辑和功能多么复杂,展示出来都是没问题的。
麻烦3:如何将这个文档应用做到简单好用。
看了上面的代码,可能有人会觉得应该没问题了。
但是我们得明白,我们这个东西是做给业务开发的人员用的,而不是做给我们自己用的。
我业务开发人员为什么要知道你这些什么 react-showdown 的代码?我业务开发人员还要学习你的这些鬼东西?不是每个人都想着学这些乱七八糟的技术好吗?我每天就只想在6点下班,就算你5分钟内给我讲明白了,你这个文档应用我用不用还两说。你要是5分钟之内还讲不明白怎么用,那你休想我在这上面给一个公共组件写文档。
我们面对的基本就是这么一个场景,我们做这个应用是为了解决项目中实际面临的问题,是面向业务开发人员编程,而不是面向领导和KPI编程。
所以我们需要做到简单好用,将所有涉及到react-showdown这玩意的部分全部不被业务开发人员感知。
想象一下,写一个组件的文档,缩减到最少,就是一个markdown文件,和一个demo.js。
那么我们就只让业务开发人员去写这两个东西就行,把他们的工作量减少到最小。
就给他们两个文件夹,一个文件夹叫doc,里面放markdown文件,一个文件夹叫demo,里面放各个demo。
再用一个字典配置dict.js,去做个基本的配置。
如果现在有个Easy组件要写文档,那么我们的dict.js内容可能就是下面这样:
const dict=['Easy','Hard','XXX']export defalt dict
只需要加个字符串Easy即可。
然后你可以在那么doc文件夹下加个markdown文件叫EasyMD.md,demo文件夹下加个文件叫EasyDemo.tsx。
之后的所有步骤全部由我们的文档应用解析dict.js后自动完成,无需用户操心。
通过这样的一种约定,我们可以将业务开发人员的工作量减到最小,把他们写组件文档的门槛降到最低。
具体代码实现就略过了,实现的关键词叫:import()函数,其他的不用多说了。
总结
虽然说这个文档应用是受前公司启发,而且因为开发时间就两天,所以比较简陋,但是至少我做到了比前公司的内部应用更简单方便,完全没有学习成本。
好了,自吹一波就得了,本篇博客到此结束。
如有疏漏之处,还请不吝赐教。
解析Markdown文件生成React组件文档相关推荐
- 使用Pandoc将Markdown文件转换为文字处理器文档
如果您以纯文本的方式生活,那么总会有一段时间有人要求文字处理程序文档. 我经常遇到这个问题,尤其是在Day Job TM上 . 尽管我已经在Docs Like Code工作流程中介绍了一个开发团队,用 ...
- 生成Swagger2静态文档
一.代码生成静态文档 <!-- swagger生成接口API --><dependency><groupId>io.springfox</groupId> ...
- VC++ MSXML创建XML文件以及对XML文档解析
VC++ MSXML创建XML文件以及对XML文档解析 转自http://www.newxing.com/Tech/Program/Cpp/703.html // XmlCreationDemo.cp ...
- Swagger2生成在线接口文档并导出pdf文件
文章目录 一,配置 1,pom依赖 2,通用配置 二,注解 三,主题 1,默认主题效果 2,添加依赖 3,添加配置 4,启动看效果 四,token验证 方法1,所有接口上添加 方法2,全局统一添加 五 ...
- matlab怎么生成html文件怎么打开吗,什么是Mathworks生成Matlab HTML文档的方法?
我正在处理共享的Matlab代码,我们希望在本地网络中分享生成的文档作为可搜索的HTML文档. 我知道以下方法来生成文档: >将转换器写入C-like文件.这是在Using Doxygen wi ...
- storybook初探:利用storybook构建组件文档库
storybook初探:利用storybook构建组件文档库 之前的一些项目上用到了storybook来构建组件的文档库,虽不够完善,但仍总结了一些简单的内容以供回顾. Storybook常用来打造团 ...
- 使用docsify+markdown+vditor构建gitlab pages文档库
前几天策划写了一个word文档来整理补充一些内容,当时就比较感慨,如果是Web文档就好了,可以超链接过去,也不必东一个文档,西一个文档的查找. 确实如此,工作这么久,各个公司的策划案都是使用的Word ...
- python生成api文档_Django 自动生成api接口文档教程
最近在写测试平台,需要实现一个节点服务器的api,正好在用django,准备使用djangorestframework插件实现. 需求 实现一个接口,在调用时,通过传递的参数,直接运行对应项目的自动化 ...
- python api接口生成_Django 自动生成api接口文档教程
最近在写测试平台,需要实现一个节点服务器的api,正好在用django,准备使用djangorestframework插件实现. 需求 实现一个接口,在调用时,通过传递的参数,直接运行对应项目的自动化 ...
最新文章
- uboot引导kernel - 2- uboot/kernel需要放在DDR什么位置的问题
- java命令--jmap命令使用
- 中国电信计划构建安全新平台
- springboot-自动配置原理
- 北斗导航 | GNSS卫星导航天线在车载高精度定位领域中的应用与挑战
- 【Qt Tips】QLineEdit内容过滤之setValidator和setInputMask浅析
- Kubernetes事件离线工具kube-eventer正式开源
- 查看Oracle实例的EM端口
- Python如何从社交用户信息中寻找潜在客户?
- Vue2.0 相对于Vue1.0的变化:生命周期
- oracle查询多个加锁,解析oracle对select加锁的方法以及锁的查询 转
- 数据库文件有哪些格式以及类型呢?
- express to eSATA卡测试
- Dukto 傻瓜安装教程
- 简单文本分割器V1.0发布(包括源码)
- Ubuntu下制作deb包的方法详解
- 边缘计算平台能力开放
- 使用 libgps 库获取gps数据
- php如何配置gii,PHP Framework YII的里的gii设置。
- mysql中的/、div的区别
热门文章
- VC导入导出二维数组到 .txt
- C++ reinterpret_cast,const_cast等 显式类型转换总结
- php 分布式环境 启动,极简.高性能.分布式框架,可运行于多种环境(apache/php-fpm,swoole)...
- lda主题评论文本python_利用python做LDA文本分析,该从哪里入手呢?
- Django 笔记2 -- Django 项目
- python3精要(48)-os命令
- 【小白学习PyTorch教程】十四、迁移学习:微调ResNet实现男人和女人图像分类
- 【深度学习】新人如何入门Pytorch的路线?有哪些资源推荐?
- 【NLP】中文BERT上分新技巧,多粒度信息来帮忙
- 【数据竞赛】大规模数据调参用这个包就可以啦。