Mermaid Kanban 图表语法详解看板结构、任务元数据与 ticket 配置实战【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaidMermaid 的 Kanban看板图表用于以列 卡片的形式可视化任务在各类工作流阶段中的流转状态。本篇基于仓库官方文档 docs/syntax/kanban.md 展开完整覆盖看板语法、任务元数据{ ... }、ticketBaseUrl配置项与完整示例并结合 kanban.jison 语法文件、kanbanDb.ts 与 kanbanRenderer.ts 等源码说明每一处语法背后实际的解析、建模与渲染机制。读完本文你可以直接编写带负责人、工单链接和优先级色条的看板图并能定位其底层实现。图的基本结构kanban 关键字Kanban 图表以kanban关键字开头后接各列阶段定义列下方以缩进方式挂载任务。最小可运行示例如下要点首行kanban声明图表类型在 docs/syntax/kanban.md 的示例中同时给出了mermaid-example与mermaid两种代码块形式column1是列的唯一标识符[Column Title]是显示的列标题task1[Task Description]必须缩进在所属列之下缩进关系决定了任务归属哪一列。定义列Columns列代表工作流的不同阶段例如 Todo、In Progress、Done 等。每一列通过唯一标识符 方括号标题定义columnId[Column Title]columnId列的唯一标识符[Column Title]显示在列头部区域的标题例如id1[Todo]。源码视角列其实是第一层节点从 kanban.jison 的statement规则看列和任务在语法层是同一种node语句| SPACELIST node shapeData { yy.addNode($1.length, $2.id, $2.descr, $2.type, $3); } | SPACELIST node { yy.addNode($1.length, $2.id, $2.descr, $2.type); }关键在$1.length——语句前导空格SPACELIST的长度被当作节点的level缩进层级传入addNode。随后 kanbanDb.ts 中的getSection(level)逻辑第 25-48 行负责判定当前节点是列还是任务节点层级与第一个节点即列层级相同 → 视为列推入sections数组层级更深 → 归属最近一列parentId指向该列若出现比列层级更浅、又不在 sections 中的节点会抛出错误Items without section detected这正是任务必须缩进在列之下这一文档约束的底层来源。此外nodeWithoutId规则kanban.jison 第 146-149 行说明列标题也可以不写显式 id[In progress]这种写法会直接以描述文本作为 id这在官方完整示例中确有使用见下文。在列中添加任务Tasks任务以缩进方式列在所属列下同样采用唯一标识符 方括号描述的格式taskId[Task Description]taskId任务的唯一标识符[Task Description]任务描述文本。文档给出的示例docs[Create Documentation]任务描述支持较长的多行文本渲染时自动换行例如完整示例中的Create renderer so that it works in all cases. We also add some extra text here for testing purposes...这由 e2e/diagrams/kanban/4-should-handle-the-height-of-a-section-with-a-wrapping-node-at-the-end.mmd 等测试用例专门覆盖换行卡片对列高影响的场景。为任务添加元数据Metadata可以使用{ ... }语法为每个任务附加元数据元数据中可包含assigned负责人、ticket工单号、priority优先级等键值对渲染时会附加显示在任务卡片上支持的元数据键assigned指定任务负责人ticket将任务关联到某个工单或 issue 编号priority表示任务紧急程度文档明确列出的允许取值为Very High、High、Low与Very Low。源码视角元数据按 YAML 解析{ ... }的识别在词法器中完成——kanban.jison 第 24-47 行 定义了SHAPE_DATA词元含对双引号嵌套状态的处理语法将拼接后的字符串作为shapeData传入addNode。在 kanbanDb.ts 的 addNode 中shapeData被包成 YAML 对象后以yaml.JSON_SCHEMA解析并逐字段提取label覆盖任务显示文本icon图标assigned、ticket转为字符串挂到节点上priority原样保留。也就是说{ ... }内部实际是一份 YAML键名区分大小写值可以用引号包裹字符串。优先级到颜色的映射文档列出的四个优先级在渲染层被映射为卡片左侧的一条色带。查看 kanbanItem.ts 的 colorFromPriority 可以看到完整映射priority 值渲染效果Very High红色色条redHigh橙色色条orangeMedium无色条null源码额外支持的中间档Low蓝色色条blueVery Low浅蓝色条lightblue色条的绘制位于 kanbanItem.ts 第 137-152 行在卡片矩形左侧x 2处追加一条stroke-width: 4的竖线上下端点按圆角半径rx内缩。可以看到源码还额外支持了文档未提及的Medium档位渲染为无色条从源码结构看这是为未来扩展预留的中间优先级。配置项ticketBaseUrl 与工单外链可以通过在 Markdown 文件开头的配置块自定义 Kanban 图表。目前 Kanban 图表有一个配置项ticketBaseUrl用于设置工单的基础 URL--- config: kanban: ticketBaseUrl: https://yourproject.atlassian.net/browse/#TICKET# ---工作机制当某个任务带有ticket元数据时图中的工单号会变成链接指向外部工单系统。ticketBaseUrl提供基础 URL其中的#TICKET#占位符会被任务元数据中的 ticket 值替换从而拼出完整链接。该配置的 schema 定义可参考 config.schema.yaml 中的kanban段ticketBaseUrl字段第 1131 行附近。源码视角链接如何被插入 SVG在 kanbanItem.ts 第 43-53 行if (ticket in kanbanNode kanbanNode.ticket config?.kanban?.ticketBaseUrl) { ticketUrl config?.kanban?.ticketBaseUrl.replace(#TICKET#, kanbanNode.ticket); link shapeSvg .insertSVGAElement(svg:a, :first-child) .attr(class, kanban-ticket-link) .attr(xlink:href, ticketUrl) .attr(target, _blank); }三个条件缺一不可节点有ticket字段、ticket 非空、配置了ticketBaseUrl。满足后工单号文本会被包裹进a元素类名kanban-ticket-linktarget_blank新窗口打开而assigned负责人则渲染在卡片右上角见 第 77-105 行 的insertLabel与坐标偏移逻辑。渲染布局要点kanbanRenderer.ts 的draw函数揭示了列与卡片的布局规则第 46-89 行每列宽度读取conf?.kanban?.sectionWidth默认200列按顺序从左到右排布section.x WIDTH * cnt ...卡片宽度为列宽减去1.5 * padding依次向下堆叠列高根据卡片总高动态计算最小 50并加上列标题占位高度若出现列中再嵌套分组会直接抛出Groups within groups are not allowed in Kanban diagrams错误——看板图不支持两级以上分组。完整示例官方文档给出的完整看板示例包含配置块、无 id 列、长文本卡片与全部元数据键该示例覆盖了无显式 id 的列Todo、[In progress]、同名字符串节点两处[Create Documentation]与[Create Blog about the new diagram]、超长换行卡片、assigned/ticket/priority三种元数据的单独与组合使用以及ticketBaseUrl配置。仓库中与之对应的端到端测试数据位于 e2e/diagrams/kanban/例如 10-full-example.mmd、7-should-handle-external-tickets.mmd、7-should-handle-prioritization.mmd 与 8-should-handle-assignments-prioritization-and-tickets-ids-in-the-same-item.mmd分别验证换行列高、外部工单链接、优先级色条与三要素混合场景可用作回归验证的参考样本。编写要点小结以kanban关键字起始列用columnId[Column Title]定义阶段名要唯一任务用taskId[Task Description]定义并缩进在所属列下缩进层级决定归属出现无列任务会被 kanbanDb.ts 直接报错拒绝可选元数据用{ key: value, ... }附加内部按 YAML 解析支持assigned、ticket、priorityVery High/High/Low/Very Low源码中另有Medium中间档顶部 frontmatter 配置块中设置config.kanban.ticketBaseUrl并保留#TICKET#占位符即可让工单号自动链接到外部工单系统优先级会渲染为卡片左侧色条Very High 红、High 橙、Low 蓝、Very Low 浅蓝见 kanbanItem.ts。遵循唯一标识符 正确缩进 元数据 配置项这几条准则即可用 Mermaid 构建出能映射真实项目工作流、并直连工单系统的完整看板图。本文所引文档源文件为 packages/mermaid/src/docs/syntax/kanban.md站点文档 docs/syntax/kanban.md 为其自动生成的副本请勿直接编辑。【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/7 2:25:33 · 阅读 1.2k Mermaid Kanban 图表语法详解：看板结构、任务元数据与 ticket 配置实战
Mermaid Kanban 图表语法详解看板结构、任务元数据与 ticket 配置实战【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaidMermaid 的 Kanban看板图表用于以列 卡片的形式可视化任务在各类工作流阶段中的流转状态。本篇基于仓库官方文档 docs/syntax/kanban.md 展开完整覆盖看板语法、任务元数据{ ... }、ticketBaseUrl配置项与完整示例并结合 kanban.jison 语法文件、kanbanDb.ts 与 kanbanRenderer.ts 等源码说明每一处语法背后实际的解析、建模与渲染机制。读完本文你可以直接编写带负责人、工单链接和优先级色条的看板图并能定位其底层实现。图的基本结构kanban 关键字Kanban 图表以kanban关键字开头后接各列阶段定义列下方以缩进方式挂载任务。最小可运行示例如下要点首行kanban声明图表类型在 docs/syntax/kanban.md 的示例中同时给出了mermaid-example与mermaid两种代码块形式column1是列的唯一标识符[Column Title]是显示的列标题task1[Task Description]必须缩进在所属列之下缩进关系决定了任务归属哪一列。定义列Columns列代表工作流的不同阶段例如 Todo、In Progress、Done 等。每一列通过唯一标识符 方括号标题定义columnId[Column Title]columnId列的唯一标识符[Column Title]显示在列头部区域的标题例如id1[Todo]。源码视角列其实是第一层节点从 kanban.jison 的statement规则看列和任务在语法层是同一种node语句| SPACELIST node shapeData { yy.addNode($1.length, $2.id, $2.descr, $2.type, $3); } | SPACELIST node { yy.addNode($1.length, $2.id, $2.descr, $2.type); }关键在$1.length——语句前导空格SPACELIST的长度被当作节点的level缩进层级传入addNode。随后 kanbanDb.ts 中的getSection(level)逻辑第 25-48 行负责判定当前节点是列还是任务节点层级与第一个节点即列层级相同 → 视为列推入sections数组层级更深 → 归属最近一列parentId指向该列若出现比列层级更浅、又不在 sections 中的节点会抛出错误Items without section detected这正是任务必须缩进在列之下这一文档约束的底层来源。此外nodeWithoutId规则kanban.jison 第 146-149 行说明列标题也可以不写显式 id[In progress]这种写法会直接以描述文本作为 id这在官方完整示例中确有使用见下文。在列中添加任务Tasks任务以缩进方式列在所属列下同样采用唯一标识符 方括号描述的格式taskId[Task Description]taskId任务的唯一标识符[Task Description]任务描述文本。文档给出的示例docs[Create Documentation]任务描述支持较长的多行文本渲染时自动换行例如完整示例中的Create renderer so that it works in all cases. We also add some extra text here for testing purposes...这由 e2e/diagrams/kanban/4-should-handle-the-height-of-a-section-with-a-wrapping-node-at-the-end.mmd 等测试用例专门覆盖换行卡片对列高影响的场景。为任务添加元数据Metadata可以使用{ ... }语法为每个任务附加元数据元数据中可包含assigned负责人、ticket工单号、priority优先级等键值对渲染时会附加显示在任务卡片上支持的元数据键assigned指定任务负责人ticket将任务关联到某个工单或 issue 编号priority表示任务紧急程度文档明确列出的允许取值为Very High、High、Low与Very Low。源码视角元数据按 YAML 解析{ ... }的识别在词法器中完成——kanban.jison 第 24-47 行 定义了SHAPE_DATA词元含对双引号嵌套状态的处理语法将拼接后的字符串作为shapeData传入addNode。在 kanbanDb.ts 的 addNode 中shapeData被包成 YAML 对象后以yaml.JSON_SCHEMA解析并逐字段提取label覆盖任务显示文本icon图标assigned、ticket转为字符串挂到节点上priority原样保留。也就是说{ ... }内部实际是一份 YAML键名区分大小写值可以用引号包裹字符串。优先级到颜色的映射文档列出的四个优先级在渲染层被映射为卡片左侧的一条色带。查看 kanbanItem.ts 的 colorFromPriority 可以看到完整映射priority 值渲染效果Very High红色色条redHigh橙色色条orangeMedium无色条null源码额外支持的中间档Low蓝色色条blueVery Low浅蓝色条lightblue色条的绘制位于 kanbanItem.ts 第 137-152 行在卡片矩形左侧x 2处追加一条stroke-width: 4的竖线上下端点按圆角半径rx内缩。可以看到源码还额外支持了文档未提及的Medium档位渲染为无色条从源码结构看这是为未来扩展预留的中间优先级。配置项ticketBaseUrl 与工单外链可以通过在 Markdown 文件开头的配置块自定义 Kanban 图表。目前 Kanban 图表有一个配置项ticketBaseUrl用于设置工单的基础 URL--- config: kanban: ticketBaseUrl: https://yourproject.atlassian.net/browse/#TICKET# ---工作机制当某个任务带有ticket元数据时图中的工单号会变成链接指向外部工单系统。ticketBaseUrl提供基础 URL其中的#TICKET#占位符会被任务元数据中的 ticket 值替换从而拼出完整链接。该配置的 schema 定义可参考 config.schema.yaml 中的kanban段ticketBaseUrl字段第 1131 行附近。源码视角链接如何被插入 SVG在 kanbanItem.ts 第 43-53 行if (ticket in kanbanNode kanbanNode.ticket config?.kanban?.ticketBaseUrl) { ticketUrl config?.kanban?.ticketBaseUrl.replace(#TICKET#, kanbanNode.ticket); link shapeSvg .insertSVGAElement(svg:a, :first-child) .attr(class, kanban-ticket-link) .attr(xlink:href, ticketUrl) .attr(target, _blank); }三个条件缺一不可节点有ticket字段、ticket 非空、配置了ticketBaseUrl。满足后工单号文本会被包裹进a元素类名kanban-ticket-linktarget_blank新窗口打开而assigned负责人则渲染在卡片右上角见 第 77-105 行 的insertLabel与坐标偏移逻辑。渲染布局要点kanbanRenderer.ts 的draw函数揭示了列与卡片的布局规则第 46-89 行每列宽度读取conf?.kanban?.sectionWidth默认200列按顺序从左到右排布section.x WIDTH * cnt ...卡片宽度为列宽减去1.5 * padding依次向下堆叠列高根据卡片总高动态计算最小 50并加上列标题占位高度若出现列中再嵌套分组会直接抛出Groups within groups are not allowed in Kanban diagrams错误——看板图不支持两级以上分组。完整示例官方文档给出的完整看板示例包含配置块、无 id 列、长文本卡片与全部元数据键该示例覆盖了无显式 id 的列Todo、[In progress]、同名字符串节点两处[Create Documentation]与[Create Blog about the new diagram]、超长换行卡片、assigned/ticket/priority三种元数据的单独与组合使用以及ticketBaseUrl配置。仓库中与之对应的端到端测试数据位于 e2e/diagrams/kanban/例如 10-full-example.mmd、7-should-handle-external-tickets.mmd、7-should-handle-prioritization.mmd 与 8-should-handle-assignments-prioritization-and-tickets-ids-in-the-same-item.mmd分别验证换行列高、外部工单链接、优先级色条与三要素混合场景可用作回归验证的参考样本。编写要点小结以kanban关键字起始列用columnId[Column Title]定义阶段名要唯一任务用taskId[Task Description]定义并缩进在所属列下缩进层级决定归属出现无列任务会被 kanbanDb.ts 直接报错拒绝可选元数据用{ key: value, ... }附加内部按 YAML 解析支持assigned、ticket、priorityVery High/High/Low/Very Low源码中另有Medium中间档顶部 frontmatter 配置块中设置config.kanban.ticketBaseUrl并保留#TICKET#占位符即可让工单号自动链接到外部工单系统优先级会渲染为卡片左侧色条Very High 红、High 橙、Low 蓝、Very Low 浅蓝见 kanbanItem.ts。遵循唯一标识符 正确缩进 元数据 配置项这几条准则即可用 Mermaid 构建出能映射真实项目工作流、并直连工单系统的完整看板图。本文所引文档源文件为 packages/mermaid/src/docs/syntax/kanban.md站点文档 docs/syntax/kanban.md 为其自动生成的副本请勿直接编辑。【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考