OutlineDriven Embed diagram
Contract
| Field | Bound contract |
|---|---|
| Trigger | The user runs /embed-diagram or asks to render a Mermaid diagram offline and embed it into a document. |
| Authority | Reversible local: writes only Mermaid source, SVG, PNG, and Excalidraw files in the output directory and edits the target document to embed the render; rollback is deleting the written files and reverting the target document edit. No remote mutation. |
| Side effect | Local SVG or PNG diagram renders written to the output directory and embedded into the target document. |
| Done | A rendered diagram is embedded in the target document. |
Inputs
- A diagram request: an English description of the structure to diagram, or Mermaid source. Required.
- A target document path. Required. The document must exist and be writable.
- Output directory. Optional. Default
./diagrams/when the cwd is a git repo, else/tmp/odin-diagrams/. - Output slug. Optional. Derived kebab-case from the diagram subject, 40 chars or fewer.
Procedure
- Bound scope. Confirm the target document path exists and is writable. Decide the output directory and slug. Do not write outside the output directory or the target document. Done when: the target document is confirmed writable and the output directory and slug are decided.
- Author Mermaid from the request. Prefer
graph LRfor pipelines and flows, andgraph TDfor hierarchies. Keep node labels short; put detail in edge labels. The readable range is 5 to 15 nodes. If the request needs more, split it into multiple diagrams and explain why. Flowcharts convert to a fully editable Excalidraw scene. Sequence, state, gantt, and other Mermaid types render to SVG and PNG but skip the Excalidraw artifact. Done when: Mermaid source is authored within the readable node range, or split into multiple diagrams with a reason. - Write the Mermaid source to
<outdir>/<slug>.mmd. The source is the single source of truth. Done when: the.mmdfile is written. - Check the local renderer toolchain. Verify
mmdc(mermaid-cli) is installed and executable. If not, stop and tell the user to install it:npm install -g @mermaid-js/mermaid-cli. Do not improvise a CDN or remote fallback. Offline is the contract. Done when:mmdcis confirmed executable, or the run stops with the install instruction. - Render SVG. Run
mmdc -i <outdir>/<slug>.mmd -o <outdir>/<slug>.svg. If the command fails, show the parse error to the user, fix the Mermaid source, and retry. Done when: the.svgfile is written. - Rasterize PNG. Run
mmdc -i <outdir>/<slug>.mmd -o <outdir>/<slug>.png -w <width>where width is computed as placed width in inches times 300. Done when: the.pngfile is written. - For flowcharts only, generate an Excalidraw scene. If the local toolchain supports Mermaid-to-Excalidraw conversion (check for
@mermaid-js/mermaid-cliExcalidraw support or a local converter script), run the converter with the Mermaid source and write the scene JSON to<outdir>/<slug>.excalidraw. For other Mermaid types, skip the Excalidraw artifact and tell the user: sequence and other non-flowchart diagrams render but are not Excalidraw-editable yet. Done when: the.excalidrawfile is written for flowcharts, or the limitation is stated for other types. - Embed the rendered SVG (preferred for documents) or PNG into the target document at the requested location. Done when: the render is embedded in the target document.
- Show the PNG to the user, list the artifact paths, and note that the
.excalidrawfile opens at excalidraw.com for editing. Done when: the PNG is shown and artifact paths are listed. - For changes, edit the
.mmdsource and re-run rendering from step 5. To re-render an edited.excalidrawscene from a user round-trip, load the scene file and export to SVG and PNG without touching the Mermaid. Done when: the change cycle is documented for both Mermaid and Excalidraw round-trips.
Failure and recovery
- Local renderer missing:
mmdcis not installed or not executable. Stop and tell the user to runnpm install -g @mermaid-js/mermaid-cli. Do not improvise a CDN or remote fallback. Offline is the contract. - Mermaid parse error: show the parse error to the user, fix the Mermaid source, and retry. Do not deliver a broken source file.
- Excalidraw conversion fails on a non-flowchart type: skip the
.excalidrawartifact, deliver the SVG and PNG, and state the limitation. - Rasterize fails: fall back to mounting the SVG in a headless browser page and taking a screenshot.
- Target document missing or unwritable: stop and state the path. Do not create or embed elsewhere.
- Partial-result rule: never ship the artifacts without rendering them. A
.mmdfile alone is not a diagram. - Rollback: rendering writes only to the output directory and the target document. A failed render leaves the target document unchanged until the embed step succeeds.
Output
A rendered diagram (SVG and PNG) embedded in the target document, plus the Mermaid source (.mmd) and, for flowcharts, an editable Excalidraw scene (.excalidraw) in the output directory. Terminal status: DONE when the embed is confirmed, BLOCKED when the renderer or target document is unavailable.