> ## Documentation Index
> Fetch the complete documentation index at: https://docs.docdiagram.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Embedded diagrams
> Create diagrams that live next to your MDX docs pages and stay updated in your repo.
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](/claude-code/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 `.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:
```
> /docdiagram:create a sequence diagram showing token refresh between the client, our API, and the auth service
```
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 `` 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:
```
> /docdiagram:update add a step for refresh-token rotation
```
```
> /docdiagram:update use dashed lines for the async calls
```
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:
```
> /docdiagram:regenerate
```
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:
```
> /docdiagram:info
```
## Commands at a glance
| Command | What it does |
| ------------------------ | ------------------------------------------------------------------------------ |
| `/docdiagram:create` | Create a diagram bound to the current MDX page and insert the image reference. |
| `/docdiagram:update` | Revise the current page's diagram with a follow-up prompt. |
| `/docdiagram:regenerate` | Re-run the chat's last prompt for a fresh revision on the same binding. |
| `/docdiagram:info` | Show the sidecar and server detail for the current page's diagram. |
## 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
The no-repo path for one-off images.
How rendered diagrams move between the server and your repo.