mkdocs-mermaid-images 0.1.0

MkDocs plugin that renders Mermaid fences to hashed PNG assets

mkdocs-mermaid-images

MkDocs plugin that replaces Mermaid code fences with generated PNG images.

Requirements

You do not need to install @mermaid-js/mermaid-cli globally. The plugin runs it through npx when MkDocs builds the site.

That means the machine running the build needs:

• node and npx available on PATH
• network access on the first run so npx can fetch @mermaid-js/mermaid-cli if it is not already cached
• any system dependencies required by Mermaid CLI's headless browser on that platform

For locked-down Linux CI environments, you may also need to disable Chromium sandboxing. The demo site does this with no_sandbox: !ENV [MKDOCS_MERMAID_IMAGES_NO_SANDBOX, false], and the GitHub Actions workflow sets that environment variable only in CI.

Demo site

A minimal demo site lives in examples/demo. It has a single page with a few Mermaid diagrams so you can verify the plugin renders them into image assets during the build.

Run it from the repository root:

uv sync
uv run mkdocs serve -f examples/demo/mkdocs.yml

Or use the Makefile targets:

make demo-serve

Or build the static site:

uv run mkdocs build -f examples/demo/mkdocs.yml

You can also run the repository checks from the root:

make ty
make test
make check

The generated files will be written to examples/demo/site/, and the rendered diagram images will appear under examples/demo/site/assets/mermaid/.