Add built-in mermaid diagram support for the markdown parser

[andrewjoelpeters]

Summary

Mermaid diagrams now render out of the box when using the markdown parser, without requiring manual JS configuration. Closes #183. Note that this does not render mermaid diagrams when using the github parser (more on that below).

Why wasn't mermaid working before?

The infrastructure for mermaid was already partially in place — js/mermaid.js, js/mermaid_config.js, and the SuperFences custom fence for mermaid were all configured in the default settings. However, MarkdownCompiler.default_js was empty ([]), so when the js setting resolved "default" for the markdown parser, no scripts were included. Users had to manually add the mermaid CDN URL and loader scripts to their js settings to get mermaid working.

Additionally, the existing mermaid.js and gitlab_config.js used mermaid v8 APIs (mermaid.mermaidAPI.globalReset(), callback-based mermaid.mermaidAPI.render(), mermaid.init()) that were removed in mermaid v10+.

What changed?

• markdown_preview.py: Added default_js to MarkdownCompiler with the mermaid CDN (v11), config, and loader scripts. Also bumped the GitlabCompiler mermaid CDN from v8 to v11.
• js/mermaid.js: Updated from the removed callback-based mermaid.mermaidAPI.render() to the modern await mermaid.render() async API. Removed the deprecated mermaid.mermaidAPI.globalReset() call.
• js/gitlab_config.js: Updated renderMermaid() from the removed mermaid.init() to the modern await mermaid.render() async API.
• Docs and examples: Updated extras.md to reflect that mermaid is now built-in for the markdown parser, updated CDN references from v8 to v11, and fixed the UML docs to use the current dict format for the js setting.

Why only the markdown parser?

The github parser delegates conversion entirely to the GitHub API, which applies its own syntax highlighting to mermaid blocks. The API returns mermaid source wrapped in syntax-highlighted HTML like <div class="highlight highlight-source-mermaid"><pre><span class="pl-k">flowchart</span>..., rather than the <pre class="mermaid"><code>...</code></pre> format that mermaid.js expects. The raw mermaid source text is broken up across multiple <span> elements with Pygments CSS classes, so it can't be passed directly to the mermaid renderer.

Adding client-side mermaid rendering on top of GitHub's API output would mean layering custom DOM-scraping logic over a third-party response format — reconstructing the original mermaid source by stripping spans and joining text nodes from GitHub's syntax-highlighted output. This works against the current, thin design of the GitHub parser, which just sends markdown to GitHub, and renders the result. Adding mermaid support there would couple us to GitHub's HTML output format in a way that's potentially fragile and harder to maintain, and maybe less intuitive to users.

If there's interest in a follow-up PR, enabling mermaid for the GitHub parser would require:

1. Adding the mermaid CDN and loader to GithubCompiler.default_js
2. Updating mermaid.js (or adding a separate GitHub-specific loader) to find div.highlight-source-mermaid elements, extract and concatenate the text content from the nested <span> elements to recover the original mermaid source, and then pass that to mermaid.render()

Potential risks

• Mermaid JS is now loaded by default for all markdown parser previews, even files without mermaid diagrams. This adds a CDN network request on every preview. Users who don't want this can override js in their settings to exclude it.
• Mermaid v11 breaking changes: The CDN was bumped from v8 to v11 for both the markdown and GitLab parsers. If any users depend on mermaid v8-specific behavior or diagram syntax, their diagrams may render differently. The v8 callback-based JS APIs were already removed in v10, so staying on v8 was not a viable long-term option.
• GitLab parser updated: The gitlab_config.js changes are a side-effect of modernizing the mermaid API usage. The GitLab parser's mermaid rendering was already broken on mermaid v10+ due to the removed mermaid.init() API, so this is effectively a bug fix.

Co-Authored-By: Claude Opus 4.6 noreply@anthropic.com

[facelessuser]

Yep, I haven't updated Mermaid support here for a bit. I will take a look, hopefully within the next couple of weeks. A lot of the logic comes from https://github.com/facelessuser/pymdown-extensions/blob/main/docs/src/js/uml.js here, which is more up to date. Regardless, we can update all of this.