基于 vite+react+md 的轻量级文档工具

不亏
664 阅读2分钟

背景

Markdown 是一门极简的、友好的语言，开发者通常依赖它描述代码库，README.md 是代码库最常见的文件之一。

ES2015(ES6) 标准中定义了 JavaScript 模块标准，如今已过去七年进入第八个年头。各个前端工具、各大浏览器厂商相继实现标准化，比如 webpack5/vite 等，chrome m61 引入 module via script 等。

从构建角度看，React 应用程序由若干模块构成，导出 React 组件的模块不妨称之为 React 模块。对一些比较关注的 React 模块，开发同学或许想描述其背景、模块特性、在线演示、接口文档等，而其中在线演示对 React 模块来说非常直观有效，尤为重要。

工具

vite-plugin-mpage 一个轻量级快速的文档工具，构建一个页面来描述你的模块，尤其是 React 组件的模块。

友好的特性

  • 实现简单。write less
  • 概念少。也不引入新概念
  • 开发体验好。支持 Markdown instant hmr

样式依赖 tailwindcss 框架单独构建一份 css。逻辑区分 node 和 client 代码，核心是 node 代码编译为 commonjs 模块以 vite 插件形式运行，依赖 vite 虚拟模块转换，client 代码会编译为 esm 模块运行于浏览器依赖 React 渲染 UI。node 代码本质是动态转换并生成 client 代码运行于浏览器。

基础用法

假设我们写个极简的计时器模块，为了达到低成本而有效的描述该模块的目标，假设我们采用了 Markdown 语法，代码大致如下：

## 模块名

> 背景描述

## 模块特性

- [x] 模块特性 1
- [x] 模块特性 2
- [ ] 模块特性 3

## 在线演示

### 基础用法

<Demo
  path="./usage1.tsx"
  title="basic usage"
  desc="basic description"
/>

## 接口文档

### ICounter

<Interface path="../Counter.tsx" name="ICounter" />

将 Mardown 模块导入 App.tsx，代码如下：

import Mpage from './demo/intro.md';

export default function App() {
  return (
    <div className="min-h-screen flex justify-center mt-10">
      <Mpage />
    </div>
  );
}

App.tsx 渲染 UI 如下图所示：

也支持的 Markdown 语法

表格、代码块、脚注、分割线、超链接、kbd、autolink literals、删除线、粗体等

典型场景

开发者可以依赖该工具快速构建组件库文档应用，同时可以依据个人喜好或团队设计风格定制布局与主题，快速交付轻量的自由定制的个性化组件库文档应用。

你可以依赖它快速构建应用例如

未来可能会做

  • 支持自定义标签/组件
  • 支持重写内置标签/组件
  • 支持深色主题与提供主题切换接口
  • 优化 Markdown 编译器实现
  • 优化 tsx 语法高亮实现
  • 提供可选的内置布局

—————————

前往 vite-plugin-mpage

avatar
文章
阅读
粉丝