Yank Note Draw.io 图形嵌入全指南链接引用与内联 XML 双模式实战【免费下载链接】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/drawio.md 功能测试文档展开系统讲解在该 Markdown 编辑器中嵌入 draw.io 架构图的两种方式——外部.drawio文件链接引用与代码块内联 XML并深入源码解析其实现原理与扩展依赖关系。读者阅读后将掌握link-typedrawio链接属性、page多页选择、--drawio--内联标记等核心用法并理解扩展缺失时的降级渲染行为。前置条件安装 Draw.io 扩展Yank Note 的 Draw.io 集成依赖官方扩展yank-note/extension-drawio。该能力是 Markdown 渲染层插件而非编辑器内置模块未安装扩展时相关语法不会生效。从源码实现看插件通过getLoadStatus(extensionId).version检测扩展是否已加载见 markdown-drawio.tsconst extensionId yank-note/extension-drawio const checkExtensionLoaded () !!getLoadStatus(extensionId).version降级渲染Fallback行为当扩展未安装时link-open与fence渲染规则会被插件拦截将链接文字与代码块内容替换为一个指向扩展管理器的安装提示链接javascript:ctx.showExtensionManager(yank-note/extension-drawio)。也就是说即使暂时没有安装扩展包含 Draw.io 语法的 Markdown 文档也不会渲染成一堆乱码链接而是给出明确的安装 Drawio 扩展引导点击即可跳转扩展管理界面。这一行为在测试用例 zero-render-plugins.ts 中有完整验证mock 扩展状态为空时链接与围栏代码块均渲染为安装提示文本mock 扩展状态存在version: 1.0.0后则回退到默认渲染逻辑。方式一链接引用外部.drawio文件基础语法在 Markdown 中只要给普通链接附加{link-typedrawio}属性即可将该链接识别为 Draw.io 图嵌入点[Architecture Diagram](https://link.gitcode.com/i/6b78690c023ac7cb71f85e373fc818b4){link-typedrawio}其中./example.drawio为相对当前文档的.drawio文件路径仓库中已有实际可用的多页示例文件 test/md/example.drawiolink-type属性值为drawio字符串与 Luckysheet 表格嵌入的link-typeluckysheet属于同一套扩展属性机制参见 markdown-luckysheet.ts。设计优势链接形式是标准 Markdown 语法只是多了一个自定义属性。即使遇到不支持该属性的普通 Markdown 解析器link-type也会被当作无效属性忽略链接本身仍可点击、可跳转不会破坏文档在其他平台的可移植性。这一设计在 FEATURES_ZH-CN.md 功能说明中明确提及使用链接的形式也不会影响其他 Markdown 解析器解析。多页选择page 属性.drawio文件本质上是 XML 容器一个文件可以包含多个diagram页面。使用page属性可指定要展示的页码从 0 开始计数[Page 1](https://link.gitcode.com/i/6b78690c023ac7cb71f85e373fc818b4){link-typedrawio page0} [Page 2](https://link.gitcode.com/i/6b78690c023ac7cb71f85e373fc818b4){link-typedrawio page1}以仓库示例 test/md/example.drawio 为例其文件结构为mxfile hostapp.diagrams.net agentCodex version24.7.17 typedevice diagram idpage-1 namePage-1 mxGraphModel ... !-- Page 1 的节点与连线 -- /mxGraphModel /diagram diagram idpage-2 namePage-2 mxGraphModel ... !-- Page 2 的节点与连线 -- /mxGraphModel /diagram /mxfilepage0对应第一个diagramPage-1page1对应第二个diagramPage-2不写page属性时默认展示第一个页面。实际 .drawio 文件长什么样.drawio是 XML 格式的矢量图形文件。仓库示例中 Page-1 描绘了一条Start → Render Markdown → Preview的流程其节点定义如下节选mxCell idstart valueStart styleellipse;whiteSpacewrap;html1;fillColor#d5e8d4;strokeColor#82b366; vertex1 parent1 mxGeometry x120 y120 width120 height60 asgeometry / /mxCell mxCell idedge-1 styleendArrowclassic;html1;rounded0; edge1 parent1 sourcestart targetprocess mxGeometry relative1 asgeometry / /mxCell关键元素说明mxfiledraw.io 文件的根节点记录 host、agent、version 等元信息diagram一个页面id与name标识页面mxGraphModel页面绘图模型dx/dy为视口偏移grid控制网格吸附pageWidth/pageHeight定义画布尺寸mxCell节点或连线。vertex1表示图形节点edge1表示连线source/target引用两端节点 idstyle控制形状ellipse椭圆、rounded1圆角矩形与配色fillColor、strokeColor。方式二代码块内联 XML除了引用外部文件draw.io 图还可以直接以 XML 形式内联在 Markdown 代码块中适合小型示意、随文档分发的场景。语法要求!-- --drawio-- -- mxGraphModel root mxCell id0/ mxCell id1 parent0/ mxCell id2 valueStart stylerounded1;whiteSpacewrap; vertex1 parent1 mxGeometry x100 y100 width120 height60 asgeometry/ /mxCell mxCell id3 valueProcess stylewhiteSpacewrap; vertex1 parent1 mxGeometry x100 y200 width120 height60 asgeometry/ /mxCell mxCell id4 value styleendArrowclassic; edge1 parent1 source2 target3 mxGeometry relative1 asgeometry/ /mxCell /root /mxGraphModel识别规则对应源码 markdown-drawio.ts代码块语言token.info必须是xml代码内容首行必须包含标记--drawio--一般写成 XML 注释!-- --drawio-- --形式两个条件同时满足才会触发 Draw.io 渲染否则走默认代码高亮逻辑。测试用例 zero-render-plugins.ts 验证了边界行为内容为!-- --drawio-- --\nmxfile /时渲染为安装提示仅有mxfile /无标记时回退到默认围栏渲染fence-fallback。结构约定内联 XML 通常从mxGraphModel开始与.drawio文件相比省略了mxfile/diagram外壳。其中id0与id1parent0是必需的根层级——id1是默认父层所有业务节点vertex1与连线edge1都挂在其下连线通过source/target指向节点 id。源码实现原理Draw.io 渲染能力由 markdown-drawio.ts 插件提供通过register钩子挂载到渲染管线export default { name: markdown-drawio, register: ctx { ctx.markdown.registerPlugin(MarkdownItPlugin) ctx.editor.tapSimpleCompletionItems(items { items.push( { language: markdown, label: / []() Drawio Link, insertText: ${2:Drawio}{link-typedrawio}, block: true }, ) }) } }插件注册位置见 plugins.tsimport markdownDrawio from fe/plugins/markdown-drawio。它通过重写 markdown-it 的link_open与fence渲染规则在渲染阶段分别拦截两类语法link_open规则markdown-drawio.ts检查链接 token 的link-type属性是否等于drawio命中且扩展已加载时清空链接文本nextToken.content 后由扩展接管渲染未加载时替换为安装引导fence规则markdown-drawio.ts检查代码块语言为xml且首行含--drawio--命中后的处理与链接一致。同时插件向编辑器注册了一个快捷补全项/ []() Drawio Link插入模板为${2:Drawio}{link-typedrawio}在编辑器中输入/触发补全即可快速生成 Draw.io 链接语法。两阶段处理模型从源码结构可以推断预览阶段.drawio文件与内联 XML 经解析后交给 Draw.io 扩展渲染为交互式图形支持在 Yank Note 编辑器内直接编辑图形内容改动可回写至文件或文档导出阶段由于链接语法为标准 Markdown其他解析器可正常处理链接本身保证文档在仓库、Git 平台、其他编辑器间的通用可读性。与其他嵌入式组件的对比link-type属性机制并非 Draw.io 独有。仓库中 Luckysheet 表格采用完全相同的设计模式markdown-luckysheet.ts其 link 类型为luckysheet同时支持.json文件链接与远程 URL。二者共同构成 Yank Note 的富媒体嵌入体系drawio负责矢量架构图luckysheet负责在线表格测试文件 zero-render-plugins.ts 对两种类型的 fallback 分支均有覆盖。最佳实践清单优先使用链接引用方式将图形保存为独立.drawio文件文档中只写一行链接便于复用、版本管理与团队协作多页图善用page属性复杂架构按页面拆分单文档通过多个带page属性的链接分别引用各页小型示意用内联 XML几行节点的简单流程图可内联但注意首行!-- --drawio-- --标记不可省略否则会被当作普通 XML 代码块高亮保持链接相对路径链接指向的.drawio文件与文档放在同一目录如test/md/下的 example.drawio移动仓库时图形与文档保持相对位置不变未装扩展时查看提示若文档中出现安装 Drawio 扩展提示而非图形说明环境缺少yank-note/extension-drawio通过扩展管理器安装后即自动恢复渲染无需修改文档内容。验证与扩展阅读功能测试文档test/md/drawio.md本主题原始出处多页示例文件test/md/example.drawio含 Page-1 流程图与 Page-2 插件架构图插件实现src/renderer/plugins/markdown-drawio.ts渲染行为测试src/renderer/plugins/tests/zero-render-plugins.ts功能清单说明help/FEATURES_ZH-CN.mdDraw.io 图形小节同机制的表格嵌入src/renderer/plugins/markdown-luckysheet.ts【免费下载链接】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），仅供参考