Save Diagram Export as HTML File

Save a stored PlantUML or Mermaid diagram as one self-contained HTML file inside the diagrams root. The SVG is encoded as a data image, so renderer markup is not parsed into the HTML DOM. SVG image processing disables scripts and external resource loading. A restrictive content security policy allows only data images and inline wrapper styles. SVG text is not selectable in the exported image. Diagram source is escaped in a native collapsible block when include_source is set, and the artifact works offline without new dependencies.

Rendering uses the same path and the same rules as diagrams_render: Mermaid requires the local 'mmdc' CLI with no fallback, and PlantUML prefers a local 'plantuml' CLI, falling back to the configured remote server only when ALLOW_REMOTE_PLANTUML=true and DISABLE_REMOTE_PLANTUML is not 'true'. Remote PlantUML rendering sends diagram source to that server over HTTPS.

The finished bundle is measured before the output directories or file are created. A bundle larger than 5000000 bytes is refused. The target must end in .html (case-insensitive) and must not exist: existing files are refused atomically, never overwritten. Saved HTML files are excluded from diagram listing and CRUD tools. To replace an export, choose a different output_path or remove the existing target yourself.

Args:

• relative_path (string, required): Path to the diagram, relative to the diagrams root

• output_path (string, required): Path for the saved HTML file, relative to the diagrams root, ending in .html

• include_source (boolean, default true): Embed the diagram source in a collapsible block

Returns: A short acknowledgement as a text content block (not the HTML itself), plus a JSON summary: { "relative_path": string, // POSIX form of the source diagram "output_path": string, // POSIX form of the saved HTML file "diagram_type": "plantuml" | "mermaid", "format": "html", "bytes": number, // UTF-8 byte length of the saved HTML "svg_chars": number, // image source characters after XML preamble stripping, before base64 encoding "source_included": boolean, // whether the source block was embedded "truncated": false, // always false; over-cap is an error, never a cut file "rendered_with": "local-plantuml" | "remote-plantuml" | "mmdc" }

Examples:

• Use when: "Save the order-flow diagram as HTML inside the repo" -> relative_path="system/order-flow.puml", output_path="exports/order-flow.html"

• Use when: "Save a standalone HTML of the checkout sequence without source" -> relative_path="system/checkout.mmd", output_path="exports/checkout.html", include_source=false

• Don't use when: You want the HTML text back without writing a file (use diagrams_export, which returns the bundle and writes nothing)

• Don't use when: You want the image alone (use diagrams_render, which returns an image block)

Error Handling:

• Returns "Error: Local renderer image exceeded the 5000000-byte limit..." for oversized local SVG output before HTML bundling or persistence

• Returns "Error: No diagram found at ''" if the diagram does not exist, before any render is attempted

• Returns "Error: Mermaid rendering requires the 'mmdc' CLI..." when rendering a Mermaid diagram without mmdc installed (no fallback exists)

• Returns "Error: PlantUML rendering requires a local 'plantuml' CLI..." when no local CLI is installed and remote rendering is not explicitly enabled (set ALLOW_REMOTE_PLANTUML=true to opt in)

• Returns "Error: PlantUML rendering server responded with ..." when the opt-in remote fallback answers non-2xx

• Returns "Error: The export bundle for '' is bytes, larger than the 5000000-byte limit, so it was not saved..." when the finished bundle exceeds the cap, with nothing written

• Returns "Error: HTML export '' already exists..." if the output file already exists; choose another output_path or remove the target yourself

• Returns "Error: '' does not have the .html export extension..." if output_path does not end in .html

• Returns "Error: Refused to access path outside the diagrams root" if relative_path or output_path attempts to escape the diagrams directory

• Unexpected internal failures return a generic "Error: Unexpected internal error ..." with isError:true and are logged to stderr without source, paths, or secrets