Ant Design X Markdown Mini

面向小程序的流式友好、轻量、跨端 Markdown 渲染器

更新日志 · 报告 Bug · 提交需求 · English · 中文

✨ 特性

以 marked 作为底层 lexer，针对小程序运行时打包并 patch —— 直出原生节点，不走 <rich-text>，无 HTML 往返。

• 🚀 为速度而生 —— 底层编译器直接 lex 成 token，无长期缓存、无阻塞。
• 🤖 流式友好，为 LLM Markdown 边出边渲而设计。
• ⚖️ 轻量 —— 内置 marked lexer，ESM 整库约 103 KB / gzip 约 25 KB，ES2018 下限。
• 📱 跨端 —— 当前支持微信与支付宝，统一组件路径，运行时自动识别。
• 🎨 原生直出 —— 渲染为 <text> / <view> / <image> / <scroll-view>，天然支持逐节点动画。
• 🔧 丰富插件 —— 按需加载 LaTeX（KaTeX）与代码高亮（highlight.js），绝不进入主包。
• 😊 兼容 —— 基于 marked 的 CommonMark 与 GFM，外加 colocated miniRenderer 扩展面。

兼容性

面向两大主流小程序运行时构建与发布，通过同一条导入路径解析，运行时自动识别（platform: 'auto'）。平台差异（如支付宝图片自动升级 https、有序列表序号以文本渲染以保证两端起始值一致）由库在渲染层抹平，无需接入方处理。

完整能力矩阵与降级规则详见 docs/platforms.md。

支持的 Markdown 规范

与 marked 保持一致：

• Markdown 1.0.0
• CommonMark
• GitHub Flavored Markdown (GFM)

📦 安装

推荐使用 npm、yarn 或 pnpm 进行开发。 便于开发调试与生产部署，充分享受整个生态与工具链的便利。

npm install @ant-design/x-markdown-mini

yarn add @ant-design/x-markdown-mini

pnpm add @ant-design/x-markdown-mini

示例

包内附带开箱即用的 Markdown / MiniNodeRenderer 小程序组件。支付宝与微信使用同一条导入路径 —— 微信通过 package.json#miniprogram 解析，支付宝读取包根。

// page.json —— 支付宝与微信写法一致
{
  "usingComponents": {
    "markdown": "@ant-design/x-markdown-mini/es/Markdown/index"
  }
}

<!-- 支付宝 page.axml -->
<markdown
  content="{{content}}"
  latex="{{true}}"
  highlight="{{true}}"
  selectable="{{true}}"
  streaming="{{ { hasNextChunk: hasNextChunk, semantic: true } }}"
  onRenderComplete="onComplete"
/>

<!-- 微信 page.wxml -->
<markdown
  content="{{content}}"
  latex
  highlight
  selectable="{{true}}"
  streaming="{{ { hasNextChunk: hasNextChunk, semantic: true } }}"
  bindrendercomplete="onComplete"
/>

latex / highlight 是布尔开关：命中后组件内部按需 require 并 bake 对应插件，未开启的页面不会为 KaTeX（约 487 KB）付出体积。元素样式以及 KaTeX、代码高亮样式都随组件加载，无需手动 @import。

编程式 API

三个入口，共享同一个单例：

import { renderNodes, render, parse } from '@ant-design/x-markdown-mini';

// 1. 给内置 <mini-node-renderer> 的节点 —— 自己渲染。
const nodes = renderNodes({ content: '# Hello\n\nWorld.', platform: 'auto', selectable: true });

// 2. marked Token[] —— 自带渲染器。render(str) === parse(str)。
const tokens = parse('# Hello');

<mini-node-renderer nodes="{{nodes}}" />

我们自己渲染这棵 MiniNode 树，而不是交给原生 <rich-text>。<rich-text> 会重新套用标签/属性白名单、屏蔽事件、无法逐节点动画 —— 而节点树本就是我们自己构建的结构化数据。

流式渲染（LLM 边出边渲）

// 每一轮：传入累计到目前为止的 markdown。
renderNodes({
  content: accumulatedMarkdown,
  platform: 'wechat',
  streaming: { hasNextChunk: true, semantic: true, enableAnimation: true },
  onPatch: (nodes) => this.setData({ nodes }),
});

// 最后一轮：hasNextChunk=false，flush 残余并触发 onRenderComplete。
renderNodes({
  content: finalMarkdown,
  platform: 'wechat',
  streaming: { hasNextChunk: false },
  onPatch: (nodes) => this.setData({ nodes }),
  onRenderComplete: () => console.log('done'),
});

被空行收尾的块会被缓存、不再重解析，仅未稳定的末段每轮重 lex。当 chunkDelay 与 charDelay 都为 0 时跳过 setTimeout，onPatch 同步推回。详见 docs/streaming.md。

插件：LaTeX 与代码高亮

按需加载，不影响主包体积（LaTeX 约 486 KB，CodeHighlight 约 184 KB）。

import { XMarkdownMini } from '@ant-design/x-markdown-mini';
import Latex from '@ant-design/x-markdown-mini/plugins/Latex';
import CodeHighlight from '@ant-design/x-markdown-mini/plugins/CodeHighlight';

const md = new XMarkdownMini({ extensions: [Latex(), CodeHighlight()] });

• Latex —— 基于 KaTeX，支持行内 $x^2$ 与块级 $$…$$。
• CodeHighlight —— 基于 highlight.js，默认支持 18 种常用语言。

使用 <Markdown> 时样式自动随组件加载。手动 @import 路径与配置详见 docs/extensions.md。

文档

• 架构 —— 流水线四步、目录结构、为何内置 marked。
• 流式 —— 增量解析、打字机模式、动画 hooks。
• 平台 —— 能力矩阵、降级规则、自定义平台。
• 扩展 —— marked 扩展、miniRenderer、Latex、CodeHighlight。

Web / H5 场景

本库专注小程序。若你需要 Web / H5 端的 Markdown 渲染，可使用同样流式友好的 @ant-design/x-markdown。

如何贡献

在参与任何形式的贡献前，请先阅读贡献者指南。若愿意贡献，欢迎提交 Pull Request 或报告 Bug。

我们强烈推荐阅读《提问的智慧》与《如何有效地报告 Bug》。好的提问更容易得到帮助。

社区支持

如果在使用过程中遇到问题，可通过以下渠道寻求帮助。我们也鼓励有经验的用户通过这些渠道帮助新人。

1. GitHub Discussions
2. GitHub Issues

License

MIT