基础
Mermaid 图表
在构建期间将 Mermaid 代码块转换成响应式、支持主题切换的 SVG 图表。
将代码块的语言设为 mermaid,Lotus 就会把它转换成静态 SVG。同一套语法可以在
Markdown 和 MDX 中使用,不需要导入组件,也不会向浏览器发送 Mermaid runtime。
快速开始
当图表需要指定无障碍名称时,在语言后添加 title="..."。省略时,renderer 会
根据图表类型生成名称。
```mermaid title="发布流程"flowchart LR Markdown --> Astro Astro --> SVG```转换会在 Astro 构建期间完成。代码块会变成包含 inline SVG 的响应式 <figure>,
因此图表能立即显示,并且在 JavaScript 被禁用时仍然可用。
支持的图表类型
图表由 beautiful-mermaid
渲染,目前支持 Mermaid 的一个明确子集:
| 图表 | 开头声明 | 适合场景 |
|---|---|---|
| 流程图 | flowchart LR 或 graph TD | 流程、判断和架构 |
| 状态图 | stateDiagram-v2 | 生命周期和状态转换 |
| 时序图 | sequenceDiagram | 请求和交互顺序 |
| 类图 | classDiagram | 类型、成员和关系 |
| 实体关系图 | erDiagram | 数据模型和基数关系 |
| XY 图表 | xychart-beta | 柱状图、折线图和组合图 |
流程图
流程图支持从上到下、从左到右、从下到上和从右到左的方向,以及标签和常用节点形状。
```mermaid title="内容发布决策"flowchart TD Draft[撰写草稿] --> Review{通过审核?} Review -->|是| Publish[发布页面] Review -->|否| Draft```状态图
当重点在于一个状态如何转变为另一个状态时,可以使用状态图。
```mermaid title="文章生命周期"stateDiagram-v2 [*] --> Draft Draft --> Review: 提交 Review --> Published: 通过 Review --> Draft: 请求修改 Published --> [*]```时序图
时序图可以直观地展示请求顺序和缓存行为,不需要冗长的过程说明。
```mermaid title="带缓存的 metadata 请求"sequenceDiagram participant Page as 页面 participant Cache as 缓存 participant Provider Page->>Cache: 解析 URL alt 已缓存 Cache-->>Page: 返回 metadata else 未缓存 Cache->>Provider: 获取 metadata Provider-->>Cache: 返回响应 Cache-->>Page: 返回 metadata end```类图
类图支持成员、方法、annotations、继承、组合、聚合、依赖和关系标签。
```mermaid title="Markdown 渲染类"classDiagram class MarkdownPage { +String title +String body +render() String } class Diagram { +String source +toSVG() String } MarkdownPage *-- Diagram```实体关系图
ER 图适合展示实体和基数关系。当关系本身最重要时,可以省略实体字段。
```mermaid title="文档内容模型"erDiagram SITE ||--o{ PAGE : contains PAGE ||--o{ DIAGRAM : renders PAGE { string slug string title } DIAGRAM { string type string source }```XY 图表
XY 图表支持柱状和折线数据系列。主数据系列使用 accent token,renderer 会据此 计算其他系列的颜色。
```mermaid title="每月文档访问量"xychart-beta title "文档访问量" x-axis [一月, 二月, 三月, 四月, 五月, 六月] y-axis "访问量(千)" 0 --> 50 bar [18, 24, 29, 31, 38, 46] line [16, 22, 27, 34, 40, 44]```明确支持的 Mermaid 子集
目前不支持 Gantt、mindmap、pie chart、user journey 和 C4 diagram。不支持的 语法会让构建失败,而不是悄悄输出空白或不完整的图表。
编写规则
-
使用准确的
mermaid语言名称。其他语言名称会继续作为普通代码块处理。
-
添加简短、明确的 title。
在代码块起始行写入
title="请求生命周期"。它会成为 SVG 的<title>, 并由aria-labelledby引用;它不是可见 caption。 -
只使用受支持的 Mermaid 语法。
beautiful-mermaid有意只实现上面列出的六类图表,而不是完整 Mermaid grammar。 -
将渲染失败视为内容错误。
无效和不支持的图表会中止构建。错误信息包含源文件和代码块行号,方便回到原处修复。
主题
生成的 SVG 使用与 Lotus 相同的 CSS custom properties,因此无需重新渲染就能 响应站点的明暗模式。
| Token | 图表用途 |
|---|---|
--pf-background | 图表背景和颜色计算 |
--pf-text | 主要标签 |
--pf-text-muted | 次要标签和 annotations |
--pf-surface | 节点表面 |
--pf-border-subtle | 节点和分组边框 |
--pf-border-muted | 连接线 |
--pf-accent | 箭头和图表数据系列 |
--pf-font-sans | 标签和标题 |
--pf-font-mono | 等宽图表文字 |
配置
Mermaid 默认启用。Lotus 还会安全地将 mermaid 添加到已有的
markdown.syntaxHighlight.excludeLangs,确保转换收到原始代码块源码。
如果要保留其他 Markdown transforms,但将 Mermaid 渲染成普通代码,可以关闭它:
import { defineConfig } from 'astro/config';import lotus from '@prosefly/astro-theme-lotus';
export default defineConfig({ integrations: [ lotus({ markdown: { mermaid: false }, }), ],});