Yank Note 中使用 Kroki 渲染多格式图表语法、示例与渲染原理全解析【免费下载链接】ynA highly extensible Markdown editor featuring version control, AI Copilot, document annotations, mind maps, document encryption, executable code snippets, chart embedding, HTML applets, plugins, and macro replacement. Its integrated sidebar terminal makes working with AI faster and more convenient.项目地址: https://gitcode.com/GitHub_Trending/yn/yn本文基于 Yank Note 仓库中的 test/md/kroki.md 测试文档系统讲解如何在 Yank Note 中通过// --kroki-- [diagram-type]标记在 JS 代码块内编写并渲染 WaveDrom、GraphViz、Ditaa、BlockDiag、SeqDiag、ActDiag、ERD、SVGBob、C4 等多种类型的图表。读完本文你将掌握 Kroki 在 Yank Note 中的完整使用方式、各图表类型的可直接复制运行的语法示例以及这类图表扩展在编辑器中的渲染机制与前置条件。Kroki 是一个统一的图表渲染服务它将几十种不同的图表 DSL领域特定语言通过一个统一的 API 聚合起来在服务端完成 SVG/PNG 等格式的渲染。Yank Note 借助yank-note/extension-kroki扩展把这一能力接入 Markdown 编辑流程你不需要为每种图表单独安装本地渲染工具只需在代码块中声明图表类型预览时即可看到渲染结果。前置条件安装扩展在开始使用之前需要先确认两点当前 Yank Note 已启用扩展功能已安装yank-note/extension-kroki扩展。这一点在原测试文档开头的 Note 中明确标注Requires theyank-note/extension-krokiextension。仓库的 test/md/README.md 的“Extension Requirements”一节也把yank-note/extension-kroki列为 Kroki 多格式图表Kroki multi-format diagrams的必备扩展与yank-note/extension-mermaid、yank-note/extension-echarts、yank-note/extension-drawio、yank-note/extension-markmap等并列。从源码结构看这类“按需扩展”的图表功能通常带有一个“扩展未安装”的降级提示。以同为图表扩展的 Mermaid 为例src/renderer/plugins/markdown-mermaid.ts 中的逻辑是当检测到yank-note/extension-mermaid尚未加载时遇到mermaid语言围栏fence代码块不直接渲染图表而是渲染一个指向扩展管理器ctx.showExtensionManager的安装提示链接扩展加载完成后才走正常的渲染路径。可以推断Kroki 扩展采用了类似的注册与提示机制因此如果预览区出现安装提示而非图表优先检查扩展是否已安装并重新加载预览。核心语法// --kroki--标记Kroki 图表统一使用JavaScript 代码块承载代码块第一行写入标记// --kroki-- [diagram-type]其中[diagram-type]为图表类型标识例如wavedrom、graphviz、ditaa、blockdiag、seqdiag、actdiag、erd、svgbob、c4plantuml等。标记行之后的内容即该图表 DSL 的源码由扩展提取后提交给 Kroki API 在服务端渲染。这种“在代码块首行放置特殊标记”的模式与 Yank Note 内置的其他代码块扩展一脉相承例如 markdown-code-run.ts 通过检查代码块首行是否包含--run--来决定是否注入“运行代码”按钮src/renderer/plugins/markdown-code-run.ts其插件钩子挂载在 markdown-it 的fence渲染规则上。Kroki 扩展对fence的拦截方式与之同理先解析token.info语言标识与首行标记再决定走默认渲染还是图表渲染。注意示例统一使用js作为代码块围栏语言标记行是注释形式//因此即使在没有安装扩展的普通 Markdown 查看器中打开也只是一个普通的 JS 代码块不会破坏文档的可读性。数字时序图WaveDromWaveDrom 用于绘制数字电路中的时序波形图Timing Diagram语法基于 JSON。下面的示例绘制了clk时钟、data数据、req请求、ack应答四路信号// --kroki-- wavedrom { signal: [ { name: clk, wave: p.....|... }, { name: data, wave: x.345x|.x, data: [head, body, tail, data] }, { name: req, wave: 0.1..0|1.0 }, {}, { name: ack, wave: 1.....|01. } ] }要点wave字段使用紧凑的字符编码描述电平变化如p表示时钟脉冲0/1表示低/高电平x表示未知.表示延续上一状态|用于划分周期段需要标注数值时用data数组与wave中的数字位如3、4、5一一对应空对象{}用于在信号之间插入一条空白分隔行。有向图GraphViz (DOT)GraphViz 的 DOT 语言适合绘制节点与连线构成的有向图、流程图。下面示例使用rankdirLR让布局从左到右并定义了带填充色的节点样式// --kroki-- graphviz digraph G { rankdirLR; node [shapebox, stylefilled, fillcolorlightblue]; A [labelInput]; B [labelProcess]; C [labelOutput]; D [labelLog]; A - B; B - C; B - D [styledashed]; }要点node [shapebox, stylefilled, fillcolorlightblue]为全部节点统一设置形状、填充样式与颜色A - B声明边B - D [styledashed]声明带虚线样式的边label属性用于自定义节点显示文本。ASCII 艺术图DitaaDitaa 可以把用 ASCII 字符绘制的方框、连线草图直接“翻译”成美观的图形。示例通过|、、-画出三个方框、箭头和文字说明// --kroki-- ditaa -------- ------- ------- | --- ditaa | | | | Text | ------- |diagram| |Document| |!magic!| | | | {d}| | | | | ------- ------- ------- : ^ | Lots of work | -------------------------要点用、-、|组合出方框边界方框内直接写文字!magic!是 Ditaa 的占位符语法表示这里不需要生成图形元素{d}放在方框内可调整文档框的圆角外观:、^、等符号用于绘制指引线与箭头。BlockDiag 系列BlockDiagBlockDiag 家族BlockDiag、SeqDiag、ActDiag、NwDiag使用同一套描述风格。BlockDiag 用于绘制方框图支持分组与颜色设置// --kroki-- blockdiag blockdiag { A - B - C - D; A - E - F - G; group { label Group 1; color #FF9900; A; B; C; } group { label Group 2; color #3399FF; E; F; } }要点A - B - C - D;一行即可串联多个节点group { ... }声明节点分组label设置组名color设置组背景色十六进制颜色值。序列图SeqDiagSeqDiag 用于绘制时序/序列图描述消息在参与者之间的传递顺序// --kroki-- seqdiag seqdiag { browser - webserver [label GET /index.html]; browser -- webserver; browser - webserver [label POST /form]; browser -- webserver; browser - webserver [label GET /image.png]; browser -- webserver; }要点-表示发送消息--表示返回消息[label ...]为消息添加文字同一对参与者之间可以反复收发多条消息用于描述一次完整的交互过程。活动图ActDiagActDiag 用于绘制活动/流程图支持lane泳道按角色划分活动区域// --kroki-- actdiag actdiag { write - convert - review lane user { label User write [label Write document]; review [label Review result]; } lane engine { label Engine convert [label Convert to HTML]; } }要点write - convert - review声明活动的流转顺序lane声明泳道label命名泳道泳道内的节点[label ...]可自定义显示文本适合表达“用户操作”与“引擎处理”等跨角色的流程。实体关系图ERDERD 用于绘制数据库表之间的实体关系// --kroki-- erd [Person] *name height weight [Pet] *name breed Person *--* Pet要点[表名]声明实体其下的*字段表示主键字段普通字段直接写字段名Person *--* Pet声明两个实体间的关系*--*表示多对多同理可推*--多对一、--*一对多等关系线写法。ASCII 艺术转 SVGSVGBobSVGBob 可以将 ASCII 风格的线条画转换为 SVG 矢量图// --kroki-- svgbob .---. /-o-/-- .-/ / /- ( * \/ -. \ \ / 要点直接使用/、\、-、(、)、.、等字符绘制轮廓与线条o常用来表示节点/眼睛等圆形元素渲染后会被矢量化为圆。C4 架构图C4 PlantUMLC4 模型是描述软件架构的标准化方法Context、Container、Component、Code 四层。通过c4plantuml类型可直接复用 PlantUML 的 C4 宏库// --kroki-- c4plantuml startuml !include C4_Context.puml Person(user, User, A user of Yank Note) System(yn, Yank Note, Markdown editor) System_Ext(ext, Extensions, Plugin system) Rel(user, yn, Uses) Rel(yn, ext, Loads) enduml要点!include C4_Context.puml引入 C4 上下文图宏由 Kroki 服务端预置Person、System、System_Ext分别声明人员、系统与外部系统Rel声明关系与关系描述文字。支持的图表类型一览根据 test/md/kroki.md 的 Notes 说明Kroki 通过统一 API 支持非常多的图表类型本文档覆盖的包括类型标识图表用途章节wavedrom数字时序波形图上文 WaveDromgraphvizDOT 有向图/流程图上文 GraphVizditaaASCII 草图转图形上文 Ditaablockdiag方框图上文 BlockDiagseqdiag序列图上文 SeqDiagactdiag活动图上文 ActDiagnwdiag网络架构图与 BlockDiag 同族erd实体关系图上文 ERDsvgbobASCII 线条画转 SVG上文 SVGBobc4plantumlC4 架构图基于 PlantUML上文 C4原文档同时指出除上述类型外还有更多and more。实际可用类型以所使用 Kroki 服务的支持范围为准常见的还包括mermaid、plantuml、bpmn、bytefield、nomnoml、pikchr、vega、umlet、dbml等。你可以在任意 JS 代码块中把[diagram-type]换成目标类型并填入对应 DSL 源码来验证。渲染原理服务端渲染原测试文档明确指出Kroki 图表是通过 Kroki API 在服务端渲染的Diagrams are rendered server-side via the Kroki API。这意味着编写阶段只需写图表 DSL 源码不需要在本地安装 GraphViz、Ditaa 等任何渲染二进制渲染质量、字体与布局由服务端统一保证同一份 DSL 在任意设备上结果一致由于渲染依赖网络与外部服务离线环境下图表可能无法显示这是与本地渲染类扩展如内置的 PlantUML的主要差异。对比仓库中内置的 PlantUML 实现可以更直观地理解“服务端渲染”这类方案的形态在 src/renderer/plugins/markdown-plantuml.ts 中插件通过md.block.ruler.before(fence, ...)与md.renderer.rules.fence两条 markdown-it 钩子拦截startuml ... enduml块把 DSL 用pako压缩并 Base64 编码后拼接到location.origin /api/plantuml上作为图片src渲染为imgsrc/renderer/plugins/markdown-plantuml.ts并在导出 HTML 时通过VIEW_ON_GET_HTML_FILTER_NODE钩子将图片内联或转为 PNGsrc/renderer/plugins/markdown-plantuml.ts。Kroki 扩展的“DSL 源码 → 编码 → 请求渲染服务 → 输出图片”链路与此高度相似只是把渲染端点从本机服务换成了 Kroki API。从 markdown-plantuml.ts 还可以看到内置图表插件普遍会向编辑器注册“快捷补全”tapSimpleCompletionItemsKroki 扩展大概率同样会提供// --kroki--代码块模板的自动补全输入// --kroki--后可通过补全菜单快速插入对应类型的骨架。与其他图表方案的定位差异Yank Note 本身是高度可扩展的 Markdown 编辑器图表能力由多条路线提供在 test/md/README.md 的“Diagrams Visualization”一节中可以看到全貌方案图表类型渲染方式Mermaid扩展流程图、时序、类图、甘特、饼图等客户端 JS 渲染PlantUML内置时序、用例、类、活动、组件、状态等本地/内置服务渲染ECharts扩展折线、柱状、饼、散点、雷达客户端 JS 渲染Draw.io扩展draw.io 图表客户端渲染Kroki扩展数十种 DSL 统一接入服务端 API 渲染Kroki 的核心价值在于“多”它不替代 Mermaid 或 PlantUML 的体验而是把 WaveDrom、Ditaa、BlockDiag 系列、ERD、SVGBob、C4 等小众但实用的图表类型统一收进同一套// --kroki--语法里让文档作者不必为每种图表安装独立插件。小结在 Yank Note 中渲染 Kroki 图表的完整流程可以归纳为四步安装yank-note/extension-kroki扩展并确保其已加载在文档中新建一个 JS 代码块js首行写入// --kroki-- [diagram-type]其中类型替换为目标图表标识在标记行之后粘贴对应 DSL 源码切换到预览视图即可看到服务端渲染出的图表。把 test/md/kroki.md 中的 WaveDrom、GraphViz、Ditaa、BlockDiag、SeqDiag、ActDiag、ERD、SVGBob、C4 九个示例依次复制到自己的文档中验证是上手最快的方式这些示例同时也是一份天然的语法速查表可随时查阅。若某个类型渲染异常优先确认扩展是否已加载、类型标识拼写是否正确、网络是否能访问 Kroki 渲染服务。【免费下载链接】ynA highly extensible Markdown editor featuring version control, AI Copilot, document annotations, mind maps, document encryption, executable code snippets, chart embedding, HTML applets, plugins, and macro replacement. Its integrated sidebar terminal makes working with AI faster and more convenient.项目地址: https://gitcode.com/GitHub_Trending/yn/yn创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考