前言

最近做的项目使用了微前端框架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 (
<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}!</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,通过这个扩展可以对代码块做高亮处理。

麻烦2react-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 | <ButtonDemo />`; <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组件文档的更多相关文章

  1. 解放生产力,自动化生成vue组件文档

    一.现状 Vue框架在前端开发中应用广泛,当一个多人开发的Vue项目经过长期维护之后往往会沉淀出很多的公共组件,这个时候经常会出现一个人 开发了一个组件而其他维护者或新接手的人却不知道这个组件是做什么 ...

  2. vite插件-自动生成vue组件文档

    特点 支持热更新 快速启动,依赖于 vite,无需另起服务 自动生成组件导航 ui 采用了vant-ui的样式 核心方法覆盖率达到了 92.86% 使用 yarn add vite-plugin-vu ...

  3. Markdown 文件转化为work文档

    1. 电脑安装pandoc 链接:https://pan.baidu.com/s/12H5wLO0JWph5TjrbeJI6mg 密码:ssgs 下载安装包解压即可用.记得配置系统环境变量 2.命令行 ...

  4. Docz 用 MDX 写 React UI 组件文档

    Docz 用 MDX 写 React UI 组件文档 前言 为了提升开发效率,创建一套 UI 组件库是一种较为有效的方式之一:可以减少重复工作.提高可复用,所以现在越来越多团队开始创建自己的 UI 组 ...

  5. 打造自己的Vue组件文档生成工具

    程序员最讨厌的两件事情,第一种是写文档,另一种是别人没有写文档.有没有直接根据vue组件生成文档的呢?当然是有的的.但第三方使用起来不一定能和现有项目结合使用,往往需要额外的注释用来标记提取信息.使用 ...

  6. 使用多个项目生成Xml文件来显示帮助文档

    终于到这了,我们首先将Product单独作为一个项目 WebAPI2PostMan.WebModel 并引用他,查看文档如下. 你会发现,你的注释也就是属性的描述没有了.打开App_Data/XmlD ...

  7. react解析markdown文件

    当当当又get到了一个新技能,使用react-markdown来直接解析markdown文件(咳咳,小菜鸟的自娱自乐) 项目中遇到了一个API的那种展示方式,类似于入门手册啥的那种,如果是一个个调用接 ...

  8. XML解析之sax解析案例(一)读取contact.xml文件,完整输出文档内容

    一.新建Demo2类: import java.io.File; import javax.xml.parsers.SAXParser; import javax.xml.parsers.SAXPar ...

  9. java生成复杂word文档

    在Web应用中,有时需要按照固定的模板将数据导出到Word,如流程审批单,在流程处理完成后将处理过程按照流程单的要求导出,有时程序中需要实现生成 标准Word文档,要求能够打印,并且保持页面样式不变, ...

  10. 使用Swagger2Markup归档swagger生成的API文档

    文章出处: http://blog.didispace.com/swagger2markup-asciidoc/ 说明 项目中使用Swagger之后,我们能够很轻松的管理API文档,并非常简单的模拟接 ...

随机推荐

  1. Python virtualenv安装库报错SSL: CERTIFICATE_VERIFY_FAILED

    Python virtualenv安装库报错SSL: CERTIFICATE_VERIFY_FAILED 问题描述 使用pip按照virtualenv报错,如下: pip install virtua ...

  2. html-制作导航菜单

    导航菜单nav: 1.使用列表标签<ul> 2.使用浮动布局float 3.使用超链接标签<a>:要使用<a>标签的margin外边距,需要让<a>标签 ...

  3. Json常见问题

    1.创建包含 JSON 语法的 JavaScript 字符串: var txt = '{ "employees" : [' + '{ "firstName":& ...

  4. JSONPath使用

    JSONPath是fastjson在1.2.0之后支持的.JSONPath是一个很强大的功能.关于JSONPath的介绍请查看官方文档 JSONPath. 官方文档上给出了详细的说明以及使用.但是官方 ...

  5. 基于Keil软件的MCU环境搭建

    我们在开发一款新的MCU的时候,偶尔会遇到Keil软件没有对应的Device设备选型,以下,我们以STM32F407VGT6作为实例来演示整个环境的搭建过程: 一.如下所示,我需要选择的是ST公司的S ...

  6. 利用pandas将numpy数组导出生成excel

    代码 # -*- coding: utf- -*- """ Created on Sun Jun :: @author: Bruce Lau ""&q ...

  7. Oracle基本操作,Oracle修改列名,Oracle修改字段类型

    oracle基本操作,Oracle修改列名,Oracle修改字段类型 >>>>>>>>>>>>>>>>& ...

  8. Android开机广播和关机广播

    有些时候我们需要我们的程序在系统开机后能自动运行,这个时候我们可以使用Android中的广播机制,编写一个继承BroadcastReceiver的类,接受系统启动关闭广播.代码如下: /** *@au ...

  9. 源自人脑的神奇算法 -- 读《How to make your own neural network》有感

    最近读到了一本很好的关于机器学习-深度学习的书值得推荐下并特意做了这个学习总结. 为什么推荐 在我认为好书(计算机类)的评判有几个标准: 试图以通俗的语言阐述,并在引入任何新概念的时候都讲述来龙去脉, ...

  10. iOS开发之int,NSInteger,NSUInteger,NSNumber的使用

    1.首先先了解下NSNumber类型: 苹果官方文档地址:https://developer.apple.com/library/ios/documentation/Cocoa/Reference/F ...