Skip to main content
Open a page, create the diagram, commit the image and sidecar, revise with update

A diagram bound to a page, committed to your repo, revised in place

Embedded diagrams are bound to a docs page. DocDiagram keeps the editable source on the server, your repo carries the rendered image plus a small sidecar file that links the two, and you refine the diagram over time with follow-up prompts. This is the workflow for documentation you maintain in a Git repo (Mintlify and similar MDX tooling).
Finish Setup first. Embedded diagrams also need an open .mdx file in your project and a Git repo with a GitHub remote, so the server can scope the diagram to your repo and page.

​
How it fits together

  • The server is the source of truth for the editable canonical: the diagram source, the chat history, and the revision graph.
  • Your repo carries the rendered image (SVG by default) plus a sidecar <page>.docdiagram.json that points back at the server record.
  • Re-running on the same page edits the same diagram. The server appends to the bound chat rather than starting over.

​
1. Create a diagram for a page

Open the .mdx page you want the diagram on, then run:
Claude resolves your repo and the page path, generates the diagram, writes the rendered image and the sidecar JSON next to your MDX file, and inserts an image reference such as ![Token refresh](./token-refresh.docdiagram.svg) into the page.
Commit the rendered image and the .docdiagram.json sidecar alongside your MDX. They are how the diagram is found and re-rendered later.

​
2. Refine it

To change a diagram, describe the change. The skill reuses the bound chat, so the model sees the previous revision as the starting point:
Each update is a new revision on the same binding and re-writes the image in your repo.

​
3. Regenerate without retyping

Want a fresh take on the current prompt without describing a change? Re-run the last prompt against the model:
Use this when a diagram drifted or you just want another sample.

​
4. Inspect a page’s diagram

To see the sidecar metadata and the current server-side detail for the diagram bound to the open page:

​
Commands at a glance

​
Create vs update

Running /docdiagram:create on a page that already has a diagram does not make a second one. The server returns the existing diagram and tells you to use /docdiagram:update. One page slot, one diagram.

​
A note on quality

Every generation forks the closest match in a curated library of chart examples and adapts it to your prompt. The model does not draw from scratch, so output quality is bounded by that library, not the prompt alone. Clear, specific prompts still help, but a vague prompt will not produce something the library cannot support.

​
Next

Standalone diagrams

The no-repo path for one-off images.

Repo sync

How rendered diagrams move between the server and your repo.