All jobs

Add Mermaid Diagrams to a MkDocs Site

Yes. An agent adds the Mermaid fence to mkdocs.yml via pymdownx.superfences, writes your diagrams as Mermaid blocks, checks them in a browser, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the site's Markdown configuration before it adds a fence. In a documentation site laid out like encode/httpx, mkdocs.yml uses the material theme with a custom_dir of docs/overrides, two palettes toggled between light and dark, a nav of about two dozen pages under Introduction, QuickStart, Advanced, Guides, API Reference and Community, and three markdown_extensions: admonition, codehilite with css_class: highlight, and mkautodoc for the API pages. requirements.txt pins mkdocs 1.6.1, mkdocs-material 9.6.18 and mkautodoc 0.2.0, scripts/docs runs mkdocs serve, and the test-suite.yml workflow has a "Build package & docs" step, so a configuration that breaks the build breaks CI.

Material for MkDocs renders Mermaid itself: from version 8.2 it initialises the Mermaid runtime on any page that contains a mermaid code block, styles flowcharts, sequence, class, state and entity-relationship diagrams in the site's fonts and colours, and follows the light and dark palettes the site already defines. What it needs is for the fence to reach the page as a <pre class="mermaid"> block rather than highlighted code, which is the job of pymdownx.superfences with a custom fence named mermaid, class mermaid, and format: !!python/name:pymdownx.superfences.fence_code_format. pymdown-extensions comes with mkdocs-material, so requirements.txt gains nothing. The agent adds that block to markdown_extensions and keeps codehilite: SuperFences takes over fenced code blocks and hands ordinary ones to CodeHilite when pymdownx.highlight is not configured, and the agent confirms it by building and checking that an existing Python fence still carries the highlight class in the output HTML.

Then the diagrams. The prompt names the pages and what each diagram should show; in a client library like this one the natural candidates are a sequence diagram on the transports page for a request going from Client through the transport to the connection pool and back, and a flowchart on the timeouts page for which of the four timeouts applies at each stage of a request. The agent writes each as a fenced mermaid block in the page's Markdown, next to the prose it illustrates, and keeps the diagrams to the five types Material styles, since pie, gantt and git graphs render but are not laid out for narrow screens.

It runs mkdocs build --strict, which turns warnings into failures, then mkdocs serve and opens each changed page in the sandbox's browser in both palettes, keeping a screenshot of every diagram so the pull request shows what the reader will see rather than the source. A diagram that overflows on a narrow viewport is rewritten top-to-bottom rather than left-to-right. If the site's docs/overrides replaces a template block that Material's scripts depend on, the build shows it as a diagram that does not render, which the agent would report rather than work around.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add Mermaid diagrams to this MkDocs site. Read mkdocs.yml, requirements.txt, scripts/docs, the docs directory and any overrides directory first. Add pymdownx.superfences with a custom fence named mermaid, class mermaid and format pymdownx.superfences.fence_code_format to markdown_extensions, keep the existing code highlighting extension, and add no new requirement if pymdown-extensions already comes with the theme. Write the diagrams I name as fenced mermaid blocks beside the prose they illustrate, using only flowchart, sequence, class, state or entity-relationship diagrams, laid out top to bottom where they would otherwise overflow a narrow screen. Run mkdocs build --strict, confirm an existing code fence still carries its highlight class in the built HTML, then run mkdocs serve and open every changed page in the browser in both the light and dark palette, saving a screenshot of each diagram. Open a pull request with the configuration change, each diagram's source, and its screenshots.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

The pull request changes mkdocs.yml and the Markdown pages that gained a diagram. Its description shows the markdown_extensions block as added, the source of each diagram, and a screenshot of each in the light and dark palette from the served build in the sandbox, with the mkdocs build --strict output beneath.

A reviewer reads each diagram against the prose next to it, which is a documentation review rather than a code review, checks the one line that proves existing code blocks still highlight, and merges. Nothing else on the site changes, because the fence is only active where a page uses it.

A page that later adds a mermaid block needs no further configuration, and a block with a syntax error renders as Mermaid's own error text in the browser rather than failing the build, which the pull request notes so writers know what a broken diagram looks like.

Run it on every pull request opened

An automation on the Project with a github trigger on pull_request.opened and the prompt "if this pull request adds or changes a mermaid block, build the site, serve it, open the changed page in both palettes and attach a screenshot of each diagram to your review; say whether it fits a narrow viewport" starts one run per pull request. The trigger adds the pull request after the prompt and fills in nothing else, so the run finds the blocks in the diff itself. Only work by an owner, member or collaborator fires it.

A team with several MkDocs sites sends this body once per repository from its own server, each POST /o/{org}/sessions with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own mkdocs.yml: a site on the readthedocs or mkdocs theme, which do not bundle the Mermaid runtime, gets the mkdocs-mermaid2-plugin instead and a line in requirements.txt for it.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A Mermaid block is a few lines of text that is only right once it has been rendered: the fence must reach the page unhighlighted, the existing code blocks must keep their highlighting, the diagram must fit a phone, and both palettes must be readable. The agent builds and serves the site in its own sandbox, opens the pages in a real browser, and keeps the screenshots with the pull request.

A reviewer sees the rendered diagrams rather than the source alone, and the build output proves the configuration change broke nothing. A team with several sites starts the same request across all of them at once.

Frequently asked questions

Do I need a plugin?

Not on Material for MkDocs 8.2 or later, which initialises Mermaid itself when a page contains a mermaid block. The only configuration is the pymdownx.superfences custom fence, and pymdown-extensions is already a dependency of the theme. Other themes need mkdocs-mermaid2-plugin.

Is Mermaid loaded from a CDN?

Material loads the runtime it ships with when a page needs it, so the site works without an external script. A custom Mermaid build, for a layout engine it does not include, is added through extra_javascript and has to set window.mermaid for the theme to use it.

Will my existing code blocks change?

They keep rendering. SuperFences replaces Markdown's fenced-code handling and passes ordinary fences to CodeHilite when pymdownx.highlight is not configured, so a site on codehilite keeps its highlight class. The agent confirms it in the built HTML and quotes the line.

Which diagram types should I use?

Flowcharts, sequence, class, state and entity-relationship diagrams, which Material styles and fits to the page. Pie, gantt, user-journey and git-graph diagrams render but are not laid out for narrow screens, so the agent avoids them unless the prompt asks.

More MkDocs jobs

The same job on other stacks

Keep reading