Just the Docs主题的Jekyll页面无法渲染Mermaid图表如何排查配置问题

1. 脚本引入位置错误 #

Just the Docs 主题有固定的自定义资源注入入口，你需要把Mermaid相关脚本放在_includes/custom.html文件末尾，不要随意插入其他模板文件，避免出现脚本加载顺序错误、被主题默认脚本覆盖的问题。

2. 初始化逻辑不正确 #

新版本Mermaid需要等待DOM加载完成后再执行初始化，同时需要适配主题的明暗模式切换，正确的初始化代码示例如下：

// 等待DOM加载完成
document.addEventListener('DOMContentLoaded', function() {
  // 配置Mermaid参数，适配主题明暗模式
  mermaid.initialize({
    startOnLoad: true,
    theme: window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'default',
    securityLevel: 'loose'
  });
});

如果要支持主题动态切换明暗模式，可额外添加监听代码同步切换Mermaid主题。

3. 代码块未被正确识别 #

Just the Docs 默认会将````mermaid格式的代码块渲染为普通代码块，包裹在

`标签中，Mermaid无法直接识别，需要额外添加脚本转换这类代码块：
document.querySelectorAll('pre code.language-mermaid').forEach((block) => {
  // 提取mermaid代码内容
  const content = block.textContent;
  // 创建mermaid专用div
  const mermaidDiv = document.createElement('div');
  mermaidDiv.className = 'mermaid';
  mermaidDiv.textContent = content;
  // 替换原有代码块
  block.parentNode.replaceWith(mermaidDiv);
});
// 转换完成后重新调用Mermaid渲染
mermaid.init();

4. 特殊字符被Jekyll转义 #
如果你直接在Markdown文件中写<div class="mermaid">包裹的图表代码，Jekyll的Markdown渲染器会自动转义|、-->等特殊字符，导致Mermaid解析失败，需要用Jekyll的raw标签包裹图表代码，避免转义：
{% raw %}
<div class="mermaid">
    graph TD 
    A[Client] -->|tcp_123| B(Load Balancer) 
    B -->|tcp_456| C[Server1] 
    B -->|tcp_456| D[Server2]
</div>
{% endraw %}

5. 引入的Mermaid版本不兼容 #
如果你使用的是Mermaid 10.x及以上版本，需要引入UMD格式的资源包，不要引入ES模块格式的资源，否则会出现全局找不到mermaid对象的问题，导致初始化失败。 #
内容的提问来源于stack exchange，提问作者Greenfly77