diagram poster tool
tools/diagram_poster.tsREADME.md
tools/diagram_poster.ts is a standalone Bun script that renders a YAML document — a mermaid diagram plus an "editorial shell" (kicker, headline, panels, trees, checklists, etc.) — into an HTML page styled with a fixed pastel theme, and optionally into a PNG screenshot via Playwright/Chromium. It exists because GitHub's built-in mermaid renderer intermittently fails to load in wikis; committing a pre-rendered PNG avoids that failure mode. It is explicitly not part of repodocs' zero-dependency Python core.
Sources: tools/diagram_poster.ts:L1-L14, README.md:L103-L107
The tool requires Bun, the playwright package, and a Chromium binary — none of which are needed by the core repodocs pipeline:
| Step | Command |
|---|---|
| Install Bun | curl -fsSL https://bun.sh/install | bash |
| Install playwright | cd tools && bun install |
| Install Chromium |
bunx playwright install chromium (~150 MB download) |
| Render HTML + PNG | bun tools/diagram_poster.ts tools/example-architecture.yaml --png |
Rendering writes tools/example-architecture.png (and the intermediate .html) next to the input file. To publish it, the PNG is committed into the target repo's <repo>.wiki.git and referenced as  from a wiki page.
Sources: README.md:L103-L117, tools/diagram_poster.ts:L517-L531
The CLI itself takes an input YAML path, an optional -o out.html override, and an optional --png flag:
bun tools/diagram_poster.ts input.yaml [-o out.html] [--png]
If no input is given it prints a usage message and exits 1.
Sources: tools/diagram_poster.ts:L517-L531
The input YAML is parsed with Bun.YAML.parse into a Doc object. Its top-level fields (rendered in a fixed order via the BLOCKS array) are:
| Field | Purpose |
|---|---|
kicker |
Small uppercase eyebrow label above the headline |
headline |
Page <h1>
|
sub |
Subtitle line |
mermaid |
Raw mermaid source, auto-appended with MERMAID_CLASSDEFS if it has no classDef of its own |
panel |
A titled group of sub-blocks (tree, dashrow, or checks) |
tree |
A standalone org-chart-style tree |
dashrow |
A dashed connector line with a caption |
checks |
A list of ✓/✗ items |
legend |
Colored swatches with labels |
note |
A hand-written-style annotation with an arrow (left/right/down) |
band |
A full-width dark callout bar |
footer |
Left/right footer text |
Sources: tools/diagram_poster.ts:L87-L101, tools/diagram_poster.ts:L448-L491
Inline rich-text markup is available inside most text fields via rich(): [hl]…[/hl] (yellow highlight), [hlg]…[/hlg] (green), [hlb]…[/hlb] (blue), [hls]…[/hls] (salmon), [m]…[/m] (monospace), and **bold**.
Sources: tools/diagram_poster.ts:L11-L14, tools/diagram_poster.ts:L109-L117
TreeBlock nodes (TreeNode) form a simple parent/child tree; layoutTree() computes rows by depth, sizes leaves at LEAF_W×LEAF_H (132×140) and boxes at BOX_W×BOX_H (220×64) within a fixed TREE_W of 1100, and spaces rows by GAP_Y (68px). Leaf nodes render as white cards with an optional name pill, an icon from the built-in ICONS map (person, shield, doc, funnel, gear, calc, chart, code), and a label; non-leaf nodes render as rounded boxes optionally tinted via tone. treeConnectorSvg() draws right-angle connectors with arrowheads between parent and child.
Sources: tools/diagram_poster.ts:L56-L65, tools/diagram_poster.ts:L69-L102, tools/diagram_poster.ts:L129-L300
The tool uses a fixed palette (CHIP, keyed by ChipColor) so that "one color = one role" across chips, tree tones, mermaid classDefs, and legend swatches: salmon, yellow, green, blue, purple, paper. red is aliased to salmon via COLOR_ALIAS. The overall page palette (background, ink, accent, fonts) is defined separately in the T theme object.
Sources: tools/diagram_poster.ts:L18-L52
If a mermaid block is present, render() embeds a <script type="module"> that imports Mermaid 11 from a CDN, waits for the Nunito/Geist Mono/Caveat webfonts to load, initializes Mermaid with the pastel themeVariables (matching the T palette), runs mermaid.run(), and sets document.title = 'RENDERED' as a completion signal used by the PNG exporter. Diagrams without an explicit classDef get MERMAID_CLASSDEFS appended so :::purple-style class annotations resolve to the shared palette.
Sources: tools/diagram_poster.ts:L360-L395, tools/diagram_poster.ts:L452-L459, tools/diagram_poster.ts:L485-L491
exportPng() dynamically imports playwright — a deliberate exception to avoid a static import that would break HTML-only usage — launches Chromium, opens the rendered HTML at a 1400×1100 viewport with deviceScaleFactor: 2, and waits for document.title === "RENDERED" (30s timeout). It then waits an additional fixed 800ms, noting in a comment that Mermaid sets the title before the compositor actually paints the SVG, so a real wait is needed rather than an animation-frame callback. It screenshots the .page element's bounding box and writes <input>.png next to the HTML.
Sources: tools/diagram_poster.ts:L493-L515
Sources: tools/diagram_poster.ts:L485-L531, README.md:L114-L117