Markdown PlantUML 图表

2026-01-01

1008 字5 分钟

本文介绍在 Markdown 中使用 PlantUML 以纯文本描述和生成图表的方法，说明其适合技术博客与项目文档的原因，包括图表与正文一同版本管理、修改只需改文本、与 Markdown 无缝结合。文中给出最小模板，并展示活动图、状态图、用例图、组件图、部署图、ER 图、登录与刷新令牌时序图及 C4 风格容器图示例；同时提到在 Firefly 中 plantuml 代码块会在构建阶段编码生成服务器 SVG 地址，页面端按亮暗主题切换图源并支持缩放、拖拽和全屏。适用于技术写作与文档维护场景。

由 DeepSeek 生成 · 本文章版本使用已保存摘要

Markdown 中 PlantUML 图表指南#

PlantUML 是一种使用纯文本描述图表的工具。你只需要写一段结构化语法，就可以生成时序图、类图、用例图、活动图等常见工程图。

它特别适合写在技术博客和项目文档里：

图表和正文一起版本管理，便于协作与审阅
修改图只需要改文本，适合频繁迭代
能和 Markdown 无缝结合，保持文档统一

在 Firefly 中，plantuml 代码块会在构建阶段编码并生成服务器 SVG 地址，页面端再根据亮暗主题自动切换图源，并支持缩放、拖拽和全屏交互。

如果你想快速上手，可以记住这个最小模板：

@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi
@enduml

活动图示例#

@startuml
start
:用户提交订单;
if (库存充足?) then (是)
:冻结库存;
:创建支付单;
if (支付成功?) then (是)
:生成发货单;
:通知仓库拣货;
else (否)
:取消订单;
:释放库存;
endif
else (否)
:提示缺货;
endif
stop
@enduml

状态图示例#

@startuml
[*] --> 草稿

草稿 --> 待审核 : 提交
待审核 --> 草稿 : 驳回
待审核 --> 已发布 : 审核通过
已发布 --> 已归档 : 到期归档
已发布 --> 草稿 : 撤回修改

state 已发布 {
[*] --> 可见
可见 --> 隐藏 : 手动隐藏
隐藏 --> 可见 : 恢复展示
}

已归档 --> [*]
@enduml

用例图示例#

@startuml
left to right direction
actor 游客
actor 用户
actor 管理员

rectangle 博客系统 {
usecase "浏览文章" as UC1
usecase "搜索内容" as UC2
usecase "发表评论" as UC3
usecase "点赞收藏" as UC4
usecase "审核评论" as UC5
usec

组件图示例#

@startuml
package "Firefly Site" {
[Astro App] as App
[Markdown Parser] as Parser
[PlantUML Encoder] as Encoder
[Theme Switcher] as Theme
[Search Indexer] as Search
}

cloud "PlantUML Server" as

部署图示例#

@startuml
node "User Device" {
artifact "Browser"
}

node "CDN / Edge" {
artifact "Static Assets"
}

node "Cloudflare Worker" {
artifact "SSR Handler"
}

node "PlantUML Service" {
artifact "SVG Re

ER 图示例#

$@startuml entity User { *id : uuid <<PK>> -- username : varchar email : varchar created_at : datetime } entity Post { *id : uuid <<PK>> -- author_id : uuid <<FK>> title : varchar content :$

时序图示例（登录与刷新令牌）#

@startuml
autonumber
actor User as 用户
participant Web as 前端页面
participant API as 网关接口
participant Auth as 认证服务
database Redis as 会话缓存

用户 -> 前端页面 : 输入账号密码并提交
前端页面 -> 网关接口 : POST /login
网关接口 -> 认证服务 :

C4 风格容器图示例#

$@startuml !includeurl https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml Person(user, "博客访客", "阅读文章与搜索内容") System_Boundary(system, "Firefly Blog") { Container(we$