Skip to main content

​
Overview

The diagram generator (diagram-gen/generate.py) scans all mintdocs/**/*.mdx files for mermaid code blocks, extracts each block to a .mmd source file in diagram-gen/sources/, and renders each source to a PNG in mintdocs/images/diagrams/. Both the .mmd source files and the rendered PNGs are committed to the repo.

​
Prerequisites

Node.js must be installed. Install the Mermaid CLI globally: 
npm install -g @mermaid-js/mermaid-cli
mmdc --version

​
Running the generator

From the repo root, run to render only changed or new diagrams: 
uv run python diagram-gen/generate.py
To re-render all diagrams regardless of whether their source changed or their PNG already exists: 
uv run python diagram-gen/generate.py --force

​
How incremental rendering works

On each run the generator:
  1. Extracts all mermaid blocks from every .mdx file and writes them to .mmd source files.
  2. Tracks which .mmd files had their content change compared to the previously committed version.
  3. Renders only the diagrams whose source changed or whose PNG is missing.
  4. Stages all generated .mmd and .png files with git add so the pre-commit hook picks them up cleanly.
Use --force when you need to regenerate everything — for example after changing the render width or background settings in generate.py.

​
Authoring diagrams

Follow the rules in the AGENTS.md diagram section exactly. In summary:
  1. Add a mermaid fenced code block to the MDX page:
```mermaid actions={true} placement="top-right"
graph LR
    A --> B
```
  1. Immediately after the closing fence, add a <Frame> thumbnail:
<Frame caption="View full size">
  <img src="/images/diagrams/{page-slug}--diagram-{n}.png" alt="Descriptive alt text" width="100" />
</Frame>
  1. Run the generator to produce the PNG:
uv run python diagram-gen/generate.py

​
Naming convention

FilePattern
Sourcediagram-gen/sources/{mdx-stem}--diagram-{n}.mmd
PNGmintdocs/images/diagrams/{mdx-stem}--diagram-{n}.png
{mdx-stem} is the MDX filename without extension and without the folder prefix. {n} is the 1-based index of the diagram on that page. Example — second diagram in architecture/architecture-overview.mdx:
  • Source: diagram-gen/sources/architecture-overview--diagram-2.mmd
  • PNG: mintdocs/images/diagrams/architecture-overview--diagram-2.png

​
Pre-commit hook

The .pre-commit-config.yaml at the repo root runs generate.py --check automatically before every commit that touches .mdx files. The check mode exits with code 1 if any .mmd source is out of date, prompting you to run the generator before committing. Install the hook once from the repo root: 
uv tool install pre-commit
pre-commit install