Quartz 中的 Mermaid 图表启用配置、语法写作与常见问题排查【免费下载链接】quartz a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites项目地址: https://gitcode.com/GitHub_Trending/qua/quartzQuartz 内置对 Mermaid 的支持允许你在 Markdown 笔记中直接编写流程图、时序图、时间线等多种图表并在构建为静态站点后渲染为可视化图形。本文基于当前仓库的文档与配置文件系统讲解如何在 Quartz 中启用 Mermaid、如何用代码块语法编写图表、图表如何随站点主题自动适配以及最常见的图表不显示问题的根因与修复方法读完即可在自己的站点中稳定使用 Mermaid 图表。概述Mermaid 是 Quartz 的开箱即用图表方案Mermaid 是一种基于文本的图表描述语言开发者可以用接近自然语言的语法在 Markdown 代码块中声明图表结构由渲染引擎在浏览器端绘制成图。Quartz 将 Mermaid 作为 Obsidian 兼容性能力的一部分内置支持这意味着你不需要额外安装任何 CLI 工具或构建期渲染服务图表在页面加载时动态渲染与站点主题自动匹配开启与关闭均由 ObsidianFlavoredMarkdown 插件统一管理见 ObsidianFlavoredMarkdown 插件文档。Mermaid 官方支持丰富的图表类型包括但不限于流程图flow chart、时序图sequence diagram、时间线timeline等Quartz 均可直接渲染。从仓库的 创建指南 可以看到使用 Obsidian 模板创建站点时会自动开启完整的 Obsidian Flavored Markdown 支持wikilinks、callouts、mermaid diagrams 等这正是多数 Quartz 用户使用 Mermaid 的标准路径。如何启用 MermaidMermaid 的开关位于ObsidianFlavoredMarkdown插件的mermaid配置项中默认值为true详见 ObsidianFlavoredMarkdown 插件文档 中的选项说明。Quartz v5 采用插件式架构插件配置集中在站点根目录的quartz.config.*.yaml配置文件中如 quartz.config.default.yaml。仓库自带的模板给出了真实的配置形态。以 Obsidian 模板 obsidian.yaml 为例其插件列表中的相关片段为- source: quartz-community/syntax-highlighting enabled: true options: theme: light: github-light dark: github-dark keepBackground: false order: 20 - source: quartz-community/obsidian-flavored-markdown enabled: true options: comments: true highlight: true wikilinks: true callouts: true mermaid: true parseTags: true parseArrows: true parseBlockReferences: true enableInHtmlEmbed: false enableYouTubeEmbed: true enableVideoEmbed: true enableCheckbox: true order: 30要点说明mermaid: true即开启 Mermaid 渲染设为false即可整体关闭该插件同时控制着 wikilinks、callouts、高亮、评论块等一系列 Obsidian 专属语法Mermaid 只是其一禁用插件会导致这些能力全部失效同款配置同样出现在 ttrpg.yaml 中可作为第二个参考样例。从 插件开发文档 的说明可知obsidian-flavored-markdown既是一个处理 Obsidian Flavored Markdown 语法的transformer转换器也提供components组件Mermaid 的实际渲染正是由它提供的组件在浏览器端完成的。因此若想自定义 Mermaid 的渲染行为例如引入 Mermaid 的扩展主题或安全配置需要围绕该外部插件进行而不是改动 Quartz 核心构建流程。编写 Mermaid 图表的语法在 Quartz 中编写 Mermaid 图表的方式与 Obsidian、GitHub 等生态一致创建一个语言标识为mermaid的代码块即可。原文档给出的时序图示例书写时注意代码块围栏语言必须严格写为mermaid否则会被当作普通代码块处理而不渲染代码块内容即 Mermaid 方言文本遵循 Mermaid 官方语法流程图、时序图、时间线等各自有独立的声明方式图表可以在任何 Markdown 页面中出现与其他内容标题、列表、Callout、wikilinks共存。仓库文档中还有更多 Mermaid 在真实场景中的应用实例例如 路径Paths高级指南 使用 Mermaid 流程图示意 Quartz 内部的路径处理逻辑Obsidian 兼容性文档 也给出了 Mermaid 示例代码块。你可以参考这些文档中的图表演示效果与写法。图表自动匹配站点主题Quartz 默认会让渲染出的 Mermaid 图表与站点当前主题保持一致——这意味着开启 暗色模式 后图表配色也会随之切换无需手工维护两套图表。这一行为在样式层有对应的兜底处理在 base.scss 中针对包含code.mermaid的pre元素做了特殊样式移除其默认边框避免代码块样式干扰图表的正常展示pre { // ... :has( code.mermaid) { border: none; } }从源码结构可以推断Mermaid 图表在页面中占用的就是代码块pre容器Quartz 通过上述规则把图表与普通代码块的视觉呈现区分开而主题色适配则由 Mermaid 渲染组件读取站点主题变量完成。常见问题图表不显示的根因与修复原文档特别给出了一个高频故障场景[!warning] 如果你的 Mermaid 图表明明已启用却不显示可能需要调整插件顺序让ObsidianFlavoredMarkdown排在SyntaxHighlighting之后。原因在于如果语法高亮插件先于 ObsidianFlavoredMarkdown 处理内容mermaid代码块会被语法高亮逻辑抢占处理导致 Mermaid 渲染组件永远拿不到原始的图表文本。正确顺序是SyntaxHighlighting 先行、ObsidianFlavoredMarkdown 后行。仓库模板中的order字段正是这一约束的落地实现在 obsidian.yaml 中SyntaxHighlighting 的order: 20ObsidianFlavoredMarkdown 的order: 30后者严格位于前者之后ttrpg.yaml 采用相同排序。因此如果你使用官方模板创建站点顺序已正确无需改动若手动调整过插件顺序请确保 ObsidianFlavoredMarkdown 的order大于 SyntaxHighlighting 的order。其余排查建议确认配置中mermaid: true未被关闭确认代码块语言标识为mermaid而非拼写错误确认页面发布属性允许该页面正常渲染涉及 ExplicitPublish 等发布控制插件时注意检查页面是否被过滤。小结Mermaid 是 Quartz 中成本最低、见效最快的图表方案由 ObsidianFlavoredMarkdown 插件统一管理开关通过mermaid代码块即写即得图表自动跟随站点主题官方模板已预置正确的插件顺序。遇到图表不显示时优先检查插件顺序与mermaid: true配置即可解决绝大多数问题。【免费下载链接】quartz a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites项目地址: https://gitcode.com/GitHub_Trending/qua/quartz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考