技术写作与分享：Markdown排版与图表绘制工具

可视化演示

Markdown技术写作中通过流程图、序列图与架构图提升可读性。演示Mermaid流程图、序列图与PlantUML架构图的语法结构，并展示图表配色与版本管理规范。

Markdown排版基础：先画户型图

装修的第一步永远是画户型图。再豪华的吊顶，也救不了一个没有隔断规划的房子：人住在里面，上厕所要穿过客厅，做饭要绕过卧室，一天下来多走两万步。技术文档同理，读者打开一篇文章，第一眼判断的不是字号和配色，而是标题层级。#、##、### 就是墙上的粉笔线，把“客厅”（章节）、“卧室”（小节）、“衣帽间”（更小的节）分得一清二楚。

Markdown 成为技术写作事实标准的原因，是它用最接近纯文本的低成本语法完成了排版：井号定义标题，短横线和数字定义列表，竖线画表格，大于号做引用，反引号包代码。编辑器（VS Code、Typora、Obsidian）会把纯文本实时渲染成漂亮的页面，但底层始终是这份可读的“粉笔稿”。

排版的核心规范是“层级不跳级”。从 ## 直接跳到 ####，等于从二楼直接爬到了四楼，读者气喘吁吁，目录生成、大纲视图、屏幕阅读器也全部断裂。同时每个标题下要维持适度的内容量：内容多就拆小节，小节太空就向上合并。理想状态下，任何一级标题都能同时服务于“扫读找路”和“逐段精读”两种读者。文档适合用多少个层级，与内容量之间存在一个粗略的对数关系：

合格的户型图，没有一堵墙“从地板直插天花板”把客厅劈成两半。文档的每一级标题也应当各居其位——层级分明、密度均匀，读者走进来，一眼就能找到属于自己的房间。

Mermaid流程图：一张水电走线图

户型图定完，水电师傅上场。他画的水电图不用文字啰嗦，符号与箭头就说明一切：一条线从配电箱出发，经开关到灯头，再用一个判断框标出“这里接双控”。流程图正是文档里的水电图——它把“先做什么、遇到分支怎么选、最后到哪去”用节点和箭头画成一条可以循迹的回路。

Mermaid 是一门用文本描述图表的轻量语言，像给装修师傅口头报走线：你说“从 A 到 B，B 判断一下，合格去 C，不合格回 A”，它就把图渲染出来。下面这段就是一张完整的流程图：

Mermaid 的语法要点有三条：第一，节点由“ID + 形状”定义，方括号是普通步骤，花括号是判断，圆括号是圆角框，形状就表达了语义；第二，连线有实线箭头 -->、无箭头 ---、虚线 -.-> 三种，信息流向靠箭头方向传达；第三，复杂流程可用 subgraph 把相关节点圈成一族，相当于水电图上的“回路分区”。判断一张图是否“该拆了”，可以借助圈复杂度——边越多、嵌套越深，数值越大，超过 10 就建议拆成多张：

水电图的原则是“回路清晰、接头明确”，多绕一圈都让后期检修想骂人。流程图也一样：一张图画清一条主干，分支单独成图，读者顺着箭头走完，比读十段文字都快。

graph TD    A[需求分析] --> B{方案可行?}    B -->|是| C[编码实现]    B -->|否| A    C --> D[测试验收]

Mermaid序列图：一张工序传话单

装修工地上有两类信息：一类是“水管怎么走”的空间关系，另一类是“明天瓦工进场、后天木工量尺”的时间顺序。后者靠一张工序传话单——谁先、谁后、谁回应谁，写成一排箭头，现场没有一个人会看错。序列图扮演的正是这个角色。

序列图（sequenceDiagram）描述多个参与方之间的消息顺序。参与方用 participant 声明，消息从上到下严格按时间排列：

关键语法有四条：->> 是实线同步调用，-->> 是虚线返回，-) 表示异步发出；activate 和 deactivate 画出参与者被占用的“激活条”，一眼看出谁在等待谁；Note over A, B 可以在两方之间写旁白；参与方的顺序由声明顺序决定，与消息顺序无关。序列图本质上在说一件事：任何消息序列必须遵守时间单调递增——第 i 条消息的时刻一定晚于第 i-1 条，就像工单不可能先审批后填报：

有了工序传话单，没人会追问“到底谁先动工”。接口评审时把 Mermaid 序列图往文档里一贴，服务端、客户端、数据库的调用顺序一目了然，省下的口舌比一次返工工资还多。

sequenceDiagram    participant U as 用户    participant S as 服务器    U->>S: 发送请求    S-->>U: 返回响应

Excalidraw架构图：一张餐巾纸草图

装修设计师有个习惯：谈需求时不掏 CAD，而是抽一张餐巾纸，随手画个家具摆放，线条微微抖动，字也歪歪扭扭。奇怪的是，这种“不完美”的草图反而让人敢于提意见——因为它看起来随时可以改。Excalidraw 就是工程师的餐巾纸。

当架构图需要表达模块划分、依赖关系、部署边界，而布局又没法用文本规则自动排布时，Excalidraw 是最顺手的工具。它的线条刻意带手绘抖动，天然传递“这是草稿，欢迎讨论”的信号，特别适合设计研讨会、方案评审和技术博客的概览图。

用法要点有四条：无限画布自由拖动，矩形、椭圆、箭头一应俱全；内置素材库，图标和流程元素拖拽即用，省去从零画起；多人实时协作，光标像工地上的手电筒各指一处；完成后导出 SVG 或 PNG 嵌入 Markdown，与正文混排。手绘线条的本质，是给理想坐标加了一点随机扰动——从数学上看，每个点的位置都落在以理想位置为中心的微小正态分布里，正是这点“不完美”拉近了与读者的距离：

餐巾纸草图的价值在于“可讨论”，但它的归宿是“转正”：讨论定稿后，流程关系落到 Mermaid、类关系落到 PlantUML，草图光荣退役。草稿与正稿各司其职，就像装修现场的粉笔痕最终要被真正的墙面取代。

PlantUML类图：一份物料分类清单

木工进场前，工头会给一份物料分类清单：板材归板材、五金归五金，每一根横梁标着“与哪面墙连接”。软件系统的“户型图”是类图——它回答的不是流程问题，而是结构问题：有哪些类、各自带什么成员、类与类之间是什么关系。

PlantUML 用极简文本描述 UML 图，尤其擅长类图。它把“类声明”和“关系声明”拆开写，你只管列清单，画布布局由引擎自动完成：

语法要点有三条：类名后跟花括号声明字段与方法，- 表示私有、+ 表示公有；关系线有继承 <|--、实现 ..|>、组合 *--、聚合 o--、依赖 ..>，箭头方向一律从子类指向父类、从使用方指向被使用方；布局完全自动，新增一个类只需加三行文本。类图最适合放在代码仓库里和源码一起维护，重构时类关系一变，图跟着变，文档永不撒谎。类图的核心就是一组关系箭头：

物料清单越清楚，木工干活越少返工。软件项目里 PlantUML 类图就是这份清单——它不负责讲故事，只负责把结构钉死。等你的仓库里有了它，新成员读代码的入门时间会从一周缩短到一天。

@startumlclass Car {  -engine: Engine  +start()}Car *-- Engine : 组合@enduml

图表设计规范：一册装修验收标准

装修最怕“每个师傅都有自己的审美”：这个插座装 20 厘米，那个装 50 厘米，开关方向还不统一。所以有经验的工头会带着一册验收标准进场——插座离地 30 厘米、防水刷到 1.8 米，白纸黑字，谁也别争。文档里的图表同样需要这样一册“验收标准”。

设计规范的目标不是限制创意，而是降低读者的认知税。读者每看到一张新图，都要花精力解码它的布局和颜色；如果全文档的图风格统一、信息量受控，读者的记忆带宽就会被释放出来，真正聚焦内容本身。

三条最实用的规范：第一，一图一主题，主要视觉元素控制在 7±2 个以内，超过就拆图或分组；第二，颜色要有语义且全文一致——红色表示异常、绿色表示正常、蓝色表示主流程，不要为了好看乱用；第三，术语与正文一致，图内文字能少则少，并给每张图编号，正文用“如图 3 所示”引用。人类短时工作记忆大约只能同时把握 7 个左右的信息块，超过这个数，读者就得来回数数——这跟标题层级公式背后是同一个认知规律：信息量越大，越要分层、分组、分图：

验收标准让工地不会出现“十个师傅十种插座高度”，图表规范让文档不会出现“每张图一种暗号”。规范不是枷锁，是让二十张图看起来像出自同一个人之手的魔法。

图表版本管理：一本装修日志

靠谱的工头会随身带一本装修日志：今天拆了哪面墙、为什么改水管走向、油漆色号从哪版换到哪版，逐条记下。半年后房东想改造，翻一翻日志，所有决策都有据可查。图表的生命周期管理，就是这本日志。

图表版本管理的核心前提是“文本即源码”：Mermaid 和 PlantUML 的 DSL 本身是文本，天然可以放进 Git 做版本跟踪；Excalidraw 的文件是 JSON，同样可以入库。导出的 PNG 只是“照片缓存”，如果当作唯一真源保存，文档就会越维护越乱——照片无法 diff，无法注释，无法追溯“为什么把箭头改成了虚线”。

推荐工作流是“三件套”：源码进仓库；每次改动先改 DSL、再重新渲染；CI 里自动生成图片并发布到文档站。版本号上可以套用语义化版本约定：结构或语义破坏性变更升主版本，新增节点或关系升次版本，微调样式或文字升修订号。这样一来，每次代码评审时，图表的 diff 和代码的 diff 一起出现，文档和代码永远步调一致：

装修日志记得好，几年后改造才有据可查；图表源码在仓库里，文档才能持续演化而不是腐烂。到这一步，你的文档就真正具备了“可维护性”——它不再是一堆截图的坟场，而是一条和代码同步生长的生产线。

AI 应用场景

Python 演示

# -*- coding: utf-8 -*-"""markdown_diagram_tool.py -- 检查 Markdown 标题层级并生成 Mermaid 流程图""" import re  def check_headings(lines):    """检查标题层级, 返回跳级问题列表"""    issues = []    prev_level = 0    for lineno, line in enumerate(lines, 1):        m = re.match(r'^(#{1,6})\s+(.*)$', line)        if not m:            continue        level = len(m.group(1))        title = m.group(2)        if prev_level and level - prev_level > 1:            issues.append("[行 %d] 标题「%s」从 %d 级跳到 %d 级" % (                lineno, title, prev_level, level))        prev_level = level    return issues  def build_flowchart(headings):    """把一级标题串成 Mermaid 流程图"""    nodes = [h for h in headings if h["level"] == 1]    if len(nodes) < 2:        nodes = headings    lines = ["graph TD"]    for h in nodes:        lines.append("    n%d[\"%s\"]" % (h["idx"], h["title"]))    for i in range(len(nodes) - 1):        lines.append("    n%d --> n%d" % (nodes[i]["idx"], nodes[i + 1]["idx"]))    return "\n".join(lines)  def main():    doc = """# 项目简介## 功能特性### 特性一### 特性二## 架构说明# 快速开始"""    headings = []    for lineno, line in enumerate(doc.splitlines(), 1):        m = re.match(r'^(#{1,6})\s+(.*)$', line)        if m:            headings.append({"idx": lineno, "level": len(m.group(1)),                             "title": m.group(2)})    issues = check_headings(doc.splitlines())    print("标题层级检查:", issues if issues else "全部通过, 无跳级")    print("--- 生成的 Mermaid 流程图 ---")    print(build_flowchart(headings))  if __name__ == "__main__":    main()

1. m = re.match(r'^(#{1,6})\s+(.*)$', line)用正则识别 Markdown 标题行，井号个数 1 到 6。
2. if prev_level and level - prev_level > 1:发现“二楼跳四楼”式跳级，记录问题和行号。
3. headings.append({"idx": lineno, ...})把标题连同行号存入列表，作为后续生成流程图的原料。
4. nodes = [h for h in headings if h["level"] == 1]只把一级标题当作流程主干节点，体现“文档骨架”思想。
5. " n%d --> n%d" % (...)生成 Mermaid 的连线语法，把相邻主干串联成图。
6. if __name__ == "__main__":可执行入口，让脚本既能被导入也能直接运行。

常见误区

面试题