Lotus
输入关键词搜索文档。

基础

Mermaid 图表

在构建期间将 Mermaid 代码块转换成响应式、支持主题切换的 SVG 图表。

将代码块的语言设为 mermaid,Lotus 就会把它转换成静态 SVG。同一套语法可以在 Markdown 和 MDX 中使用,不需要导入组件,也不会向浏览器发送 Mermaid runtime。

快速开始

当图表需要指定无障碍名称时,在语言后添加 title="..."。省略时,renderer 会 根据图表类型生成名称。

发布流程 Markdown Astro SVG

转换会在 Astro 构建期间完成。代码块会变成包含 inline SVG 的响应式 <figure>, 因此图表能立即显示,并且在 JavaScript 被禁用时仍然可用。

支持的图表类型

图表由 beautiful-mermaid 渲染,目前支持 Mermaid 的一个明确子集:

图表开头声明适合场景
流程图flowchart LR 或 graph TD流程、判断和架构
状态图stateDiagram-v2生命周期和状态转换
时序图sequenceDiagram请求和交互顺序
类图classDiagram类型、成员和关系
实体关系图erDiagram数据模型和基数关系
XY 图表xychart-beta柱状图、折线图和组合图

流程图

流程图支持从上到下、从左到右、从下到上和从右到左的方向,以及标签和常用节点形状。

内容发布决策 是 否 撰写草稿 通过审核? 发布页面

状态图

当重点在于一个状态如何转变为另一个状态时,可以使用状态图。

文章生命周期 提交 通过 请求修改 Draft Review Published

时序图

时序图可以直观地展示请求顺序和缓存行为,不需要冗长的过程说明。

带缓存的 metadata 请求 alt [已缓存] [未缓存] 解析 URL 返回 metadata 获取 metadata 返回响应 返回 metadata 页面 缓存 Provider

类图

类图支持成员、方法、annotations、继承、组合、聚合、依赖和关系标签。

Markdown 渲染类 MarkdownPage + title: String + body: String + render(): String Diagram + source: String + toSVG(): String

实体关系图

ER 图适合展示实体和基数关系。当关系本身最重要时,可以省略实体字段。

文档内容模型 SITE (no attributes) PAGE string slug string title DIAGRAM string type string source contains renders

XY 图表

XY 图表支持柱状和折线数据系列。主数据系列使用 accent token,renderer 会据此 计算其他系列的颜色。

每月文档访问量 一月 二月 三月 四月 五月 六月 0 10 20 30 40 50 访问量(千) 文档访问量 Bar 1 Line 1

明确支持的 Mermaid 子集

目前不支持 Gantt、mindmap、pie chart、user journey 和 C4 diagram。不支持的 语法会让构建失败,而不是悄悄输出空白或不完整的图表。

编写规则

  1. 使用准确的 mermaid 语言名称。

    其他语言名称会继续作为普通代码块处理。

  2. 添加简短、明确的 title。

    在代码块起始行写入 title="请求生命周期"。它会成为 SVG 的 <title>, 并由 aria-labelledby 引用;它不是可见 caption。

  3. 只使用受支持的 Mermaid 语法。

    beautiful-mermaid 有意只实现上面列出的六类图表,而不是完整 Mermaid grammar。

  4. 将渲染失败视为内容错误。

    无效和不支持的图表会中止构建。错误信息包含源文件和代码块行号,方便回到原处修复。

主题

生成的 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 渲染成普通代码,可以关闭它:

astro.config.ts
import { defineConfig } from 'astro/config';
import lotus from '@prosefly/astro-theme-lotus';
export default defineConfig({
integrations: [
lotus({
markdown: { mermaid: false },
}),
],
});

最后更新于 2026年9月10日

贡献者