Mermaid 配置机制全解析defaultConfig、siteConfig、Frontmatter 与 Directives 的三层配置体系【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid本文以 Mermaid 仓库的 Configuration 文档为主线系统讲解 Mermaid 启动时如何抽取并合并多来源配置覆盖 frontmatter YAML 配置、initialize站点级配置、configApi.reset重置机制等文档核心内容并结合 config.ts 与 preprocess.ts 等源码帮助读者掌握默认配置 → 站点配置 → 图表级配置的完整合并链路与安全边界sanitize能够独立完成站点级主题定制、单图级 frontmatter 覆盖以及渲染前的配置重置。一、配置来源总览三层配置与 render configMermaid 启动时会先抽取配置configuration来确定渲染某张图所用的最终配置。根据 Configuration 文档配置共有以下来源默认配置defaultConfig所有图表的底层基础代码中由 defaultConfig.ts 提供并在 config.ts 中以Object.freeze(config)冻结导出保证默认值不可被运行时意外篡改站点级覆盖siteConfig由宿主站点/应用通过initialize调用设置作用于该站点内的所有图表Frontmatterv10.5.0图表作者可以在图表代码顶部的 YAML frontmatter 中更新选定的配置参数应用到 render config 上Directives已被 Frontmatter 取代Deprecated图表作者可以在图表代码中通过%%{init: ...}%%指令直接更新配置同样应用到 render config。最终render config渲染配置是把上述各层配置按优先级合并后、真正用于渲染的配置对象。从源码结构看这一三层叠加模型在 config.ts 中体现得非常清晰——模块内部维护了四个状态变量let siteConfig: MermaidConfig assignWithDepth({}, defaultConfig); let configFromInitialize: MermaidConfig; let directives: MermaidConfig[] []; let currentConfig: MermaidConfig assignWithDepth({}, defaultConfig);即siteConfig站点配置基于默认配置深合并而来、configFromInitializeinitialize 传入的原始配置、directives累积的指令/frontmatter 配置队列和currentConfig当前实际生效的渲染配置。所有合并都通过深合并工具assignWithDepth完成保证嵌套配置项如themeVariables按深度逐项覆盖而不是整体替换。二、Frontmatter 配置在图表代码内自包含地覆盖参数Configuration 文档指出除安全配置secure configs外整个 mermaid 配置都可以由图表作者在 frontmatter 中覆盖。frontmatter 是位于图表顶部的一个 YAML 块。文档给出的示例如下这个示例同时演示了三个 frontmatter 能力title图表标题、config.theme切换主题为 base和config.themeVariables.primaryColor覆盖主题变量主色为#00ff00。2.1 frontmatter 的解析实现frontmatter 的提取逻辑在 frontmatter.ts 中。关键实现要点使用正则frontMatterRegex匹配开头的---块若无匹配则原样返回图表保持无 metadata解析前会对 YAML 体做去缩进处理js-yaml 拒绝 tab 缩进的文档使用js-yaml的JSON_SCHEMA模式解析以支持完整 JSON 类型的配置值仅提取显式支持的三个字段title、displayMode当前用于甘特图的紧凑显示模式、config其余字段会被丢弃。// frontmatter.ts 简化逻辑 let parsed yaml.load(yamlBody, { schema: yaml.JSON_SCHEMA }) ?? {}; const metadata {}; if (parsed.displayMode) metadata.displayMode parsed.displayMode.toString(); if (parsed.title) metadata.title parsed.title.toString(); if (parsed.config) metadata.config parsed.config;2.2 frontmatter 与 directives 的合并链路frontmatter 解析完成后进入预处理流程 preprocess.ts。preprocessDiagram函数按固定顺序完成四件事cleanupText统一换行符CRLF → LF、把 HTML 属性的双引号统一为单引号processFrontmatter提取 frontmatter。注意一个细节——若设置了displayMode会自动把它映射到config.gantt.displayMode为兼容旧版 gantt 紧凑模式processDirectives检测init指令和wrap指令并从代码中移除指令文本cleanAndMerge(frontMatter.config, directive.directive)将 frontmatter 配置与指令配置清洗合并得到最终的图表级配置。也就是说同一张图里 frontmatter 与 directives 并存时二者会先合并再叠加到站点配置之上——这正是 Configuration 文档所说两者都作用于 render config的具体实现。三、Mermaid 的启动时序与站点级 InitializeConfiguration 文档给出了一张启动时序图说明站点如何把配置注入 mermaid时序含义站点先调用initialize完成站点级配置随后内容加载完毕mermaid 入口再调用mermaidAPI完成内部初始化。3.1 initialize只应用一次的站点级覆盖文档强调initialize调用只生效一次由站点集成方调用来在站点层面覆盖默认配置。在 mermaid.ts 中可以看到其实现就是薄薄一层转发const initialize function (config: MermaidConfig) { mermaidAPI.initialize(config); };对应的底层 API 在 mermaidAPI.ts 中initialize会调用 config.ts 的setSiteConfigexport const setSiteConfig (conf: MermaidConfig): MermaidConfig { siteConfig assignWithDepth({}, defaultConfig); siteConfig assignWithDepth(siteConfig, conf); if (conf.theme theme[conf.theme]) { siteConfig.themeVariables theme[conf.theme].getThemeVariables(conf.themeVariables); } updateCurrentConfig(siteConfig, directives); return siteConfig; };这段源码印证了文档中覆盖默认配置的说法siteConfig总是先以冻结的 defaultConfig 打底再深合并站点传入的conf若站点指定了theme还会把该主题预置的主题变量与站点自定义的themeVariables合并保证换主题后变量取值完整。另外 config.ts 中的saveConfigFromInitialize会把 initialize 的原始配置单独保存供主题变量回退合并使用。3.2 updateSiteConfiginitialize 之外的另一种更新方式除了一次的initializeconfig.ts 还提供updateSiteConfig它不做打底重置而是在现有siteConfig之上增量深合并后重新计算currentConfig。从源码结构看适合站点在运行期间例如用户切换主题面板追加更新站点配置的场景。生成的 API 参考文档也收录了这两个函数可参见 setSiteConfig 与 updateSiteConfig。四、render config 的合并算法defaultConfig → siteConfig → directives最终生效的 render config 由 config.ts 的updateCurrentConfig计算合并优先级与文档描述完全一致const updateCurrentConfig (siteCfg: MermaidConfig, _directives: MermaidConfig[]) { // start with config being the siteConfig let cfg: MermaidConfig assignWithDepth({}, siteCfg); // Join directives let sumOfDirectives: MermaidConfig {}; for (const d of _directives) { sanitize(d); sumOfDirectives assignWithDepth(sumOfDirectives, d); } cfg assignWithDepth(cfg, sumOfDirectives); if (sumOfDirectives.theme sumOfDirectives.theme in theme) { // 用 initialize 保存的主题变量打底再叠加指令的主题变量 const themeVariables assignWithDepth( configFromInitialize?.themeVariables || {}, sumOfDirectives.themeVariables ); if (cfg.theme cfg.theme in theme) { cfg.themeVariables theme[cfg.theme].getThemeVariables(themeVariables); } } currentConfig cfg; checkConfig(currentConfig); return currentConfig; };可以归纳出四点基底是 siteConfigcfg从siteConfig深拷贝起步因此 defaultConfig 的每一项都是最终兜底值directives含 frontmatter 配置最后叠加多条指令按入队顺序依次sanitize后深合并再整体覆盖到cfg上主题变量有专门的回退合并当指令指定了theme时themeVariables会以 initialize 时保存的主题变量为底、叠加指令中的主题变量最后交给对应主题的getThemeVariables生成完整变量集——这解释了为何 frontmatter 里只写primaryColor一个变量其余主题变量仍能正确取值每次合并后都会执行checkConfig目前用于对已废弃配置项如lazyLoadedDiagrams、loadExternalDiagramsAtStartup打印一次性警告见 config.ts。此外getEffectiveHtmlLabels 展示了配置读取端的兼容处理优先取全局htmlLabels回退到已废弃的flowchart.htmlLabels并提示用全局htmlLabels替代这属于 v9→v10 配置迁移的典型模式。五、安全边界secure 配置与 sanitizeConfiguration 文档特别提到 frontmatter 除 secure configs 外均可覆盖。这条边界在 sanitize 中落地它在每次指令加入合并前被调用updateCurrentConfig循环内的sanitize(d)export const sanitize (options: any) { // 1. 禁止覆盖 siteConfig 声明的 secure 键始终包含 secure 本身 [secure, ...(siteConfig.secure ?? [])].forEach((key) { if (Object.hasOwn(options, key)) { log.debug(Denied attempt to modify a secure key ${key}, options[key]); delete options[key]; } }); // 2. 删除以 __ 开头的键防原型污染 // 3. 删除包含 、 或 url(data: 的字符串值防 XSS // 4. 递归处理对象值 };三层防护的意图在源码注释中写得很明白注释特别提醒不要在日志中用模板字符串打印被拦截的值因为恶意脚本可以利用日志器对值的序列化执行任意代码。因此站点可以把敏感键例如securityLevel相关的覆盖列入siteConfig.secure图表作者即使用 frontmatter 或init指令也无法改写指令/frontmatter 中的任何 HTML 片段、data:URL 都会被静默删除防止通过配置通道注入脚本。生成的 API 参考 sanitize 同样对应这段实现。六、configApi.reset每张图渲染前的配置归位Configuration 文档对configApi.reset的定义把某张图的配置重置回站点整体配置即站点集成方提供的配置并且在每次渲染图表之前reset 会在最开始被调用。对应实现是 config.ts 的resetexport const reset (config siteConfig): void { // Replace current config with siteConfig directives []; updateCurrentConfig(config, directives); };两个关键行为清空directives队列上一张图的 frontmatter/init 指令不会泄漏到下一张图——这正是每张图渲染前调用 reset的意义所在保证图表级配置的隔离性以 siteConfig 为新基底重算 currentConfig站点配置本身不受影响被重置掉的只是叠加在站点层之上的图表级覆盖。reset还支持传入自定义基底配置默认值为siteConfig配合 getSiteConfig返回 siteConfig 的深拷贝可以只读地获取站点配置做比对。对应的生成文档见 reset 与 getSiteConfig。值得一提的是旧式 setConfig直接改 currentConfig已被标记为deprecated文档注释明确说明对currentConfig的修改会被下一次addDirective或reset覆盖——这进一步说明当前推荐的图表级定制路径就是 frontmatter或 legacy 的 directives而站点级路径是initialize。七、实用建议与小结结合 Configuration 文档与源码实现实际集成时可以遵循以下实践站点级主题与全局参数在应用启动时调用一次mermaid.initialize({ theme, themeVariables, flowchart: {...} })让 setSiteConfig 完成 defaultConfig 打底与主题变量补全单图级定制优先使用 frontmatterv10.5.0YAML 更直观、支持任意嵌套配置例如文档示例中的config.themeconfig.themeVariables.primaryColor%%{init: ...}%%directives 属于被取代的旧方案新图不建议再写安全敏感场景在initialize时通过secure数组声明受保护键sanitize 会拦截任何来自图表作者的同名覆盖不要手动改 currentConfigsetConfig已弃用图表级配置请走 frontmatter跨图状态靠渲染前自动 reset保证隔离。小结Mermaid 的配置体系是一个默认配置冻结打底 → initialize 生成 siteConfig → frontmatter/directives 逐图叠加 → sanitize 安全过滤 → 渲染前 reset 归位的闭环。理解 config.ts 中siteConfig / configFromInitialize / directives / currentConfig四个状态变量的流转再对照 frontmatter.ts 与 preprocess.ts 的提取顺序就能准确预测任意一张图最终拿到的 render config也能在集成方与图表作者两个角色之间划清配置权限的边界。【免费下载链接】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），仅供参考 Mermaid 配置机制全解析：defaultConfig、siteConfig、Frontmatter 与 Directives 的三层配置体系
Mermaid 配置机制全解析defaultConfig、siteConfig、Frontmatter 与 Directives 的三层配置体系【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid本文以 Mermaid 仓库的 Configuration 文档为主线系统讲解 Mermaid 启动时如何抽取并合并多来源配置覆盖 frontmatter YAML 配置、initialize站点级配置、configApi.reset重置机制等文档核心内容并结合 config.ts 与 preprocess.ts 等源码帮助读者掌握默认配置 → 站点配置 → 图表级配置的完整合并链路与安全边界sanitize能够独立完成站点级主题定制、单图级 frontmatter 覆盖以及渲染前的配置重置。一、配置来源总览三层配置与 render configMermaid 启动时会先抽取配置configuration来确定渲染某张图所用的最终配置。根据 Configuration 文档配置共有以下来源默认配置defaultConfig所有图表的底层基础代码中由 defaultConfig.ts 提供并在 config.ts 中以Object.freeze(config)冻结导出保证默认值不可被运行时意外篡改站点级覆盖siteConfig由宿主站点/应用通过initialize调用设置作用于该站点内的所有图表Frontmatterv10.5.0图表作者可以在图表代码顶部的 YAML frontmatter 中更新选定的配置参数应用到 render config 上Directives已被 Frontmatter 取代Deprecated图表作者可以在图表代码中通过%%{init: ...}%%指令直接更新配置同样应用到 render config。最终render config渲染配置是把上述各层配置按优先级合并后、真正用于渲染的配置对象。从源码结构看这一三层叠加模型在 config.ts 中体现得非常清晰——模块内部维护了四个状态变量let siteConfig: MermaidConfig assignWithDepth({}, defaultConfig); let configFromInitialize: MermaidConfig; let directives: MermaidConfig[] []; let currentConfig: MermaidConfig assignWithDepth({}, defaultConfig);即siteConfig站点配置基于默认配置深合并而来、configFromInitializeinitialize 传入的原始配置、directives累积的指令/frontmatter 配置队列和currentConfig当前实际生效的渲染配置。所有合并都通过深合并工具assignWithDepth完成保证嵌套配置项如themeVariables按深度逐项覆盖而不是整体替换。二、Frontmatter 配置在图表代码内自包含地覆盖参数Configuration 文档指出除安全配置secure configs外整个 mermaid 配置都可以由图表作者在 frontmatter 中覆盖。frontmatter 是位于图表顶部的一个 YAML 块。文档给出的示例如下这个示例同时演示了三个 frontmatter 能力title图表标题、config.theme切换主题为 base和config.themeVariables.primaryColor覆盖主题变量主色为#00ff00。2.1 frontmatter 的解析实现frontmatter 的提取逻辑在 frontmatter.ts 中。关键实现要点使用正则frontMatterRegex匹配开头的---块若无匹配则原样返回图表保持无 metadata解析前会对 YAML 体做去缩进处理js-yaml 拒绝 tab 缩进的文档使用js-yaml的JSON_SCHEMA模式解析以支持完整 JSON 类型的配置值仅提取显式支持的三个字段title、displayMode当前用于甘特图的紧凑显示模式、config其余字段会被丢弃。// frontmatter.ts 简化逻辑 let parsed yaml.load(yamlBody, { schema: yaml.JSON_SCHEMA }) ?? {}; const metadata {}; if (parsed.displayMode) metadata.displayMode parsed.displayMode.toString(); if (parsed.title) metadata.title parsed.title.toString(); if (parsed.config) metadata.config parsed.config;2.2 frontmatter 与 directives 的合并链路frontmatter 解析完成后进入预处理流程 preprocess.ts。preprocessDiagram函数按固定顺序完成四件事cleanupText统一换行符CRLF → LF、把 HTML 属性的双引号统一为单引号processFrontmatter提取 frontmatter。注意一个细节——若设置了displayMode会自动把它映射到config.gantt.displayMode为兼容旧版 gantt 紧凑模式processDirectives检测init指令和wrap指令并从代码中移除指令文本cleanAndMerge(frontMatter.config, directive.directive)将 frontmatter 配置与指令配置清洗合并得到最终的图表级配置。也就是说同一张图里 frontmatter 与 directives 并存时二者会先合并再叠加到站点配置之上——这正是 Configuration 文档所说两者都作用于 render config的具体实现。三、Mermaid 的启动时序与站点级 InitializeConfiguration 文档给出了一张启动时序图说明站点如何把配置注入 mermaid时序含义站点先调用initialize完成站点级配置随后内容加载完毕mermaid 入口再调用mermaidAPI完成内部初始化。3.1 initialize只应用一次的站点级覆盖文档强调initialize调用只生效一次由站点集成方调用来在站点层面覆盖默认配置。在 mermaid.ts 中可以看到其实现就是薄薄一层转发const initialize function (config: MermaidConfig) { mermaidAPI.initialize(config); };对应的底层 API 在 mermaidAPI.ts 中initialize会调用 config.ts 的setSiteConfigexport const setSiteConfig (conf: MermaidConfig): MermaidConfig { siteConfig assignWithDepth({}, defaultConfig); siteConfig assignWithDepth(siteConfig, conf); if (conf.theme theme[conf.theme]) { siteConfig.themeVariables theme[conf.theme].getThemeVariables(conf.themeVariables); } updateCurrentConfig(siteConfig, directives); return siteConfig; };这段源码印证了文档中覆盖默认配置的说法siteConfig总是先以冻结的 defaultConfig 打底再深合并站点传入的conf若站点指定了theme还会把该主题预置的主题变量与站点自定义的themeVariables合并保证换主题后变量取值完整。另外 config.ts 中的saveConfigFromInitialize会把 initialize 的原始配置单独保存供主题变量回退合并使用。3.2 updateSiteConfiginitialize 之外的另一种更新方式除了一次的initializeconfig.ts 还提供updateSiteConfig它不做打底重置而是在现有siteConfig之上增量深合并后重新计算currentConfig。从源码结构看适合站点在运行期间例如用户切换主题面板追加更新站点配置的场景。生成的 API 参考文档也收录了这两个函数可参见 setSiteConfig 与 updateSiteConfig。四、render config 的合并算法defaultConfig → siteConfig → directives最终生效的 render config 由 config.ts 的updateCurrentConfig计算合并优先级与文档描述完全一致const updateCurrentConfig (siteCfg: MermaidConfig, _directives: MermaidConfig[]) { // start with config being the siteConfig let cfg: MermaidConfig assignWithDepth({}, siteCfg); // Join directives let sumOfDirectives: MermaidConfig {}; for (const d of _directives) { sanitize(d); sumOfDirectives assignWithDepth(sumOfDirectives, d); } cfg assignWithDepth(cfg, sumOfDirectives); if (sumOfDirectives.theme sumOfDirectives.theme in theme) { // 用 initialize 保存的主题变量打底再叠加指令的主题变量 const themeVariables assignWithDepth( configFromInitialize?.themeVariables || {}, sumOfDirectives.themeVariables ); if (cfg.theme cfg.theme in theme) { cfg.themeVariables theme[cfg.theme].getThemeVariables(themeVariables); } } currentConfig cfg; checkConfig(currentConfig); return currentConfig; };可以归纳出四点基底是 siteConfigcfg从siteConfig深拷贝起步因此 defaultConfig 的每一项都是最终兜底值directives含 frontmatter 配置最后叠加多条指令按入队顺序依次sanitize后深合并再整体覆盖到cfg上主题变量有专门的回退合并当指令指定了theme时themeVariables会以 initialize 时保存的主题变量为底、叠加指令中的主题变量最后交给对应主题的getThemeVariables生成完整变量集——这解释了为何 frontmatter 里只写primaryColor一个变量其余主题变量仍能正确取值每次合并后都会执行checkConfig目前用于对已废弃配置项如lazyLoadedDiagrams、loadExternalDiagramsAtStartup打印一次性警告见 config.ts。此外getEffectiveHtmlLabels 展示了配置读取端的兼容处理优先取全局htmlLabels回退到已废弃的flowchart.htmlLabels并提示用全局htmlLabels替代这属于 v9→v10 配置迁移的典型模式。五、安全边界secure 配置与 sanitizeConfiguration 文档特别提到 frontmatter 除 secure configs 外均可覆盖。这条边界在 sanitize 中落地它在每次指令加入合并前被调用updateCurrentConfig循环内的sanitize(d)export const sanitize (options: any) { // 1. 禁止覆盖 siteConfig 声明的 secure 键始终包含 secure 本身 [secure, ...(siteConfig.secure ?? [])].forEach((key) { if (Object.hasOwn(options, key)) { log.debug(Denied attempt to modify a secure key ${key}, options[key]); delete options[key]; } }); // 2. 删除以 __ 开头的键防原型污染 // 3. 删除包含 、 或 url(data: 的字符串值防 XSS // 4. 递归处理对象值 };三层防护的意图在源码注释中写得很明白注释特别提醒不要在日志中用模板字符串打印被拦截的值因为恶意脚本可以利用日志器对值的序列化执行任意代码。因此站点可以把敏感键例如securityLevel相关的覆盖列入siteConfig.secure图表作者即使用 frontmatter 或init指令也无法改写指令/frontmatter 中的任何 HTML 片段、data:URL 都会被静默删除防止通过配置通道注入脚本。生成的 API 参考 sanitize 同样对应这段实现。六、configApi.reset每张图渲染前的配置归位Configuration 文档对configApi.reset的定义把某张图的配置重置回站点整体配置即站点集成方提供的配置并且在每次渲染图表之前reset 会在最开始被调用。对应实现是 config.ts 的resetexport const reset (config siteConfig): void { // Replace current config with siteConfig directives []; updateCurrentConfig(config, directives); };两个关键行为清空directives队列上一张图的 frontmatter/init 指令不会泄漏到下一张图——这正是每张图渲染前调用 reset的意义所在保证图表级配置的隔离性以 siteConfig 为新基底重算 currentConfig站点配置本身不受影响被重置掉的只是叠加在站点层之上的图表级覆盖。reset还支持传入自定义基底配置默认值为siteConfig配合 getSiteConfig返回 siteConfig 的深拷贝可以只读地获取站点配置做比对。对应的生成文档见 reset 与 getSiteConfig。值得一提的是旧式 setConfig直接改 currentConfig已被标记为deprecated文档注释明确说明对currentConfig的修改会被下一次addDirective或reset覆盖——这进一步说明当前推荐的图表级定制路径就是 frontmatter或 legacy 的 directives而站点级路径是initialize。七、实用建议与小结结合 Configuration 文档与源码实现实际集成时可以遵循以下实践站点级主题与全局参数在应用启动时调用一次mermaid.initialize({ theme, themeVariables, flowchart: {...} })让 setSiteConfig 完成 defaultConfig 打底与主题变量补全单图级定制优先使用 frontmatterv10.5.0YAML 更直观、支持任意嵌套配置例如文档示例中的config.themeconfig.themeVariables.primaryColor%%{init: ...}%%directives 属于被取代的旧方案新图不建议再写安全敏感场景在initialize时通过secure数组声明受保护键sanitize 会拦截任何来自图表作者的同名覆盖不要手动改 currentConfigsetConfig已弃用图表级配置请走 frontmatter跨图状态靠渲染前自动 reset保证隔离。小结Mermaid 的配置体系是一个默认配置冻结打底 → initialize 生成 siteConfig → frontmatter/directives 逐图叠加 → sanitize 安全过滤 → 渲染前 reset 归位的闭环。理解 config.ts 中siteConfig / configFromInitialize / directives / currentConfig四个状态变量的流转再对照 frontmatter.ts 与 preprocess.ts 的提取顺序就能准确预测任意一张图最终拿到的 render config也能在集成方与图表作者两个角色之间划清配置权限的边界。【免费下载链接】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），仅供参考