Skip to content

fix(docs): enable mermaid diagrams via pymdownx.superfences custom_fences#20

Merged
jdwit merged 1 commit into
mainfrom
fix/docs-enable-mermaid
May 31, 2026
Merged

fix(docs): enable mermaid diagrams via pymdownx.superfences custom_fences#20
jdwit merged 1 commit into
mainfrom
fix/docs-enable-mermaid

Conversation

@jdwit

@jdwit jdwit commented May 31, 2026

Copy link
Copy Markdown
Owner

Summary

`docs/livestreams.md` already had a flowchart-LR mermaid block but rendered it as a literal code block because the SuperFences custom-fence handler wasn't configured.

Material for MkDocs bundles Mermaid.js automatically when the fence is declared this way; no extra plugin or runtime dependency (reference).

```yaml

  • pymdownx.superfences:
    custom_fences:
    - name: mermaid
    class: mermaid
    format: !!python/name:pymdownx.superfences.fence_code_format
    ```

Verified locally with `uv run mkdocs build --strict`: the livestreams page now emits `

` which the Material runtime upgrades into an interactive SVG diagram.

Versions confirmed against PyPI via context7:

package current floor latest
mkdocs `>=1.6` 1.6.1
mkdocs-material `>=9.5` 9.7.6
pymdown-extensions `>=10.7` 10.21.3

All current floors already accept the latest minors; no pyproject.toml change needed.

Test plan

  • `uv run mkdocs build --strict` clean
  • grep'd `site/livestreams/index.html` for `
    `
  • manual visual check on the deployed site after merge

docs/livestreams.md already contains a flowchart-LR mermaid block,
but it rendered as a literal code block because the SuperFences
custom-fences handler wasn't configured. Material for MkDocs bundles
Mermaid.js automatically when the fence is declared this way -- no
extra plugin or runtime dependency.

Verified by building locally with `uv run mkdocs build --strict`:
the livestreams page now emits `<pre class="mermaid">` which the
Material runtime upgrades into an interactive diagram.

Versions confirmed against the latest releases on PyPI via
context7 + the squidfunk reference docs:
- mkdocs 1.6.x (current floor `>=1.6` accepts 1.6.1)
- mkdocs-material 9.7.x (current floor `>=9.5` accepts 9.7.6)
- pymdown-extensions 10.21.x (current floor `>=10.7` accepts; the
  fence_code_format format has been stable since 9.x)

No pyproject.toml changes needed; the existing docs deps are
already loose enough to pull the latest minors.

See https://squidfunk.github.io/mkdocs-material/reference/diagrams/
@jdwit jdwit merged commit 6904dda into main May 31, 2026
7 checks passed
@jdwit jdwit deleted the fix/docs-enable-mermaid branch May 31, 2026 19:07
@jdwit jdwit mentioned this pull request Jun 8, 2026
2 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant