Comark 公式与图表指南:math 与 mermaid 插件如何渲染 LaTeX 和 Mermaid
Comark 公式与图表指南:math 与 mermaid 插件如何渲染 LaTeX 和 Mermaid
Comark 是一个开源 Markdown 解析与渲染库,内置的 math 插件和 mermaid 插件可以分别渲染 LaTeX 数学公式和 Mermaid 图表。只需在 Markdown 中写 $...$ 或 $$...$$、```mermaid 代码块,就能在 Vue、React、Svelte、Angular、HTML 乃至终端里看到排版好的公式和流程图。本文带你快速掌握这两个插件的用法与常见坑。
一、math 插件:LaTeX 公式一键排版
1. 安装与引入
katex 是 math 插件的 peer 依赖,需要先安装,并在应用入口导入一次样式:
npm install katex
import 'katex/dist/katex.min.css'
然后在解析或框架组件中同时传入插件和 Math 渲染组件即可。以 Vue 为例:
<script setup lang="ts">
import { Markdown } from '@comark/vue'
import math, { Math } from '@comark/vue/plugins/math'
</script>
<template>
<Markdown :components="{ math: Math }" :plugins="[math()]">{{ content }}</Markdown>
</template>
💡 详细 API 请查阅官方文档:math.md,插件核心实现位于 src/plugins/math.ts。
2. 行内公式与块级公式
| 写法 | 效果 |
|---|---|
单美元符号 $E = mc^2$ |
行内公式,跟随文字排版 |
双美元符号 $$...$$ |
块级公式,独占一行并居中 |
例如在 Markdown 里写 勾股定理:$a^2 + b^2 = c^2$,就会渲染出带上下标的行内公式;而把求根公式
$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$
写成块级公式,KaTeX 会自动以 display 模式排版。
3. 两个高频"坑",新手必看
- 金额符号不会误判为公式:插件要求
$之间至少有一个字符,且内容不能以数字开头。所以像$100、$200这样的价格会原样输出,不会被当作公式解析。 - JavaScript 字符串中的反斜杠要转义:
\f在 JS 中是转义序列,应写'\\frac{a}{b}'而不是'\frac{a}{b}',否则 LaTeX 命令会被吃掉。
插件还支持 throwOnError 选项:默认渲染出错时返回错误提示,开启后则直接抛出异常,方便开发期排查。
二、mermaid 插件:文字描述秒变图表
1. 安装与引入
beautiful-mermaid 是 mermaid 插件的 peer 依赖:
npm install beautiful-mermaid
用法与 math 插件完全对称——插件 + Mermaid 组件一起传入 <Markdown>:
<script setup lang="ts">
import { Markdown } from '@comark/vue'
import mermaid, { Mermaid } from '@comark/vue/plugins/mermaid'
</script>
<template>
<Markdown :components="{ Mermaid }" :plugins="[mermaid()]">{{ content }}</Markdown>
</template>
2. 支持的图表类型
只要在 ```mermaid 代码块里写 Mermaid 语法,浏览器端就会实时渲染成图表。常见类型包括:
- 📊 流程图(graph / flowchart):描述审批流、系统架构
- 🕐 时序图(sequenceDiagram):接口调用、模块交互
- 🧩 类图(classDiagram):面向对象设计文档
- 🚦 状态图(stateDiagram-v2):订单、任务状态机
- 📅 甘特图(gantt):项目时间线
- 🥧 饼图(pie):数据占比
- 🌿 Git 图(gitGraph):分支与合并历史
- 🗄️ ER 图(erDiagram):数据库表关系
一个最简单的流程图示例:
graph TD
A[开始] --> B{是否通过?}
B -->|是| C[完成]
B -->|否| D[重新调试]
D --> A
3. 主题与尺寸属性
借助 Comark 的代码块属性语法,可以在围栏上直接给图表传属性,无需额外 JS:
```mermaid {theme="dark" width="800px"}
graph TD
A --> B
插件也接受 `theme` / `themeDark` 配置,为深色模式单独指定主题;组件还支持 `width`、`height`、`class` 等属性,默认为 `100%` 宽度自适应容器。
> 📖 完整文档见 <a href="https://link.gitcode.com/i/af828ea9b00a28197a7e63fac9a4c00d" target="_blank">mermaid.md</a>,插件源码见 <a href="https://link.gitcode.com/i/80eed6a68d17a6b40abad23bbdb794dd" target="_blank">src/plugins/mermaid.ts</a>。
<a href="https://link.gitcode.com/i/330067ebc3009eea2ffe72b13f7f5eb7" target="_blank"></a>
## 三、跨框架使用与示例项目
Comark 的公式与图表能力对 Vue、React、Svelte、Angular 一视同仁,写法都遵循"插件 + 组件"的模式,只需更换各自的包前缀(`@comark/vue`、`@comark/react`、`@comark/svelte` 等)。仓库内置了可直接运行的示例项目:
- Vue + Vite 公式示例:<a href="https://link.gitcode.com/i/73d057565a42391a2c5a3ced190b2a58" target="_blank">examples/3.plugins/vue-vite-math/</a>
- Vue + Vite Mermaid 示例:<a href="https://link.gitcode.com/i/929090cefe3900eaa6cd1a08b2c1e9a7" target="_blank">examples/3.plugins/vue-vite-mermaid/</a>
- React 版本的公式与图表示例:<a href="https://link.gitcode.com/i/d845e012ab0c6c9ea44e753cbb6d7a19" target="_blank">examples/3.plugins/react-vite-math/</a>、<a href="https://link.gitcode.com/i/ec3c29f6ce69d03e752beb22fe6eb03a" target="_blank">examples/3.plugins/react-vite-mermaid/</a>
<a href="https://link.gitcode.com/i/a7c1f219edd941a80e3ca8b209512de1" target="_blank"></a>
## 四、常见问题速查
**Q:公式没有样式,显示成了原始 LaTeX 代码?**
检查是否在应用入口导入了 `katex/dist/katex.min.css`,并把 `Math` 组件传入了 `components`。
**Q:金额 `$100` 被误渲染成公式了吗?**
不会。插件要求 `$` 之间有内容且不能以数字开头,因此价格文本会原样保留。
**Q:Mermaid 图表在深色模式下刺眼?**
通过 `mermaid({ themeDark: '...' })` 或围栏属性 `{theme-dark="..."}` 为深色模式指定主题即可。
**Q:公式解析失败会报错中断页面吗?**
默认不会。math 插件出错时返回一段错误提示;确有需要时可将 `throwOnError` 设为 `true` 让异常抛出。
## 写在最后
Comark 的 **math 插件**和 **mermaid 插件**让"Markdown 里写公式、画图"变得像写列表一样简单:一个负责 LaTeX 公式的 KaTeX 排版,一个负责 Mermaid 图表的浏览器端渲染,并且两者都原生支持 AI 流式输出场景。配合本文提到的示例项目和官方文档,几行配置就能把公式与图表能力接入你的项目。
更多插件(脚注、高亮、TOC 等)可浏览插件总览:<a href="https://link.gitcode.com/i/bb4f8f979fa784e5ff8474e059f7cfeb" target="_blank">docs/content/4.plugins/index.md</a>。
登录后查看全文
