Gallery build pipeline

Field	Value
Type	Skill Resource
Source	~/.copilot/skills/technical-writing/references/mermaid/gallery/build/README.md
Description	Not specified

Source Content

Gallery build pipeline

The gallery at ../index.html and the catalog at ../../service-team-diagrams.md are both generated from one source of truth, diagrams.py, so the code a reader copies is the code that was rendered.

Source of truth

diagrams.py holds every diagram: its id, lifecycle group, title, Mermaid keyword, reader question, when-to-use and when-not lists, the what to notice caption, and the exact Mermaid source.

Edit that file to add, remove, or reword a diagram — never edit the generated index.html or service-team-diagrams.md by hand.

Regenerate the catalog

The Markdown catalog needs no browser:

python3 build_catalog.py
python3 ../../../../scripts/mermaid_lint.py ../../service-team-diagrams.md

Regenerate the rendered gallery

Rendering needs real Mermaid, which needs a browser. The pipeline vendors Mermaid, renders each diagram in a headless browser, harvests the SVGs, and inlines them into a self-contained gallery.html.

1. Fetch Mermaid into this folder (once):

   curl -sL https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js -o mermaid.min.js

2. Build the render harness and serve it:

   python3 build_render.py
   python3 serve.py    # serves ./render on :8191, accepts POST /save

3. Open http://localhost:8191/ in a browser. It renders every diagram and posts the SVGs to svgs.json. (Any headless-browser driver works — this repo used the Preview MCP’s managed browser plus preview_eval.)

4. Assemble the self-contained gallery and publish it:

   python3 build_gallery.py            # writes gallery.html + gallery_artifact.html
   cp gallery.html ../index.html

gallery.html is the standalone document (open it directly, or commit it as ../index.html). gallery_artifact.html is a body-only fragment for the Artifact tool.

Files

File	What it does
diagrams.py	Single source of truth for all diagrams
build_catalog.py	Emits ../../service-team-diagrams.md
build_render.py	Emits render/index.html, the render harness
serve.py	Serves the harness and saves harvested SVGs to svgs.json
build_gallery.py	Inlines the SVGs into the self-contained gallery