render-mermaid

name	render-mermaid
description	Use when the user asks you to analyze a repository, draw an architecture diagram, analyze a workflow/process, or explain something through a visual diagram. Prefer this skill whenever structured relationships, flows, states, sequences, or decision paths need to be communicated clearly. Do not use for general image generation or non-Mermaid charting tools.

Render Mermaid

Render Mermaid diagrams to PNG/SVG/HTML using the official Mermaid renderer.

Workflow

Progress Checklist

Render Mermaid Progress:
- [ ] Step 0: Check setup (EXTEND.md + deps) -- BLOCKING
- [ ] Step 1: Generate Mermaid source code
- [ ] Step 2: Route by output_mode → render diagram
- [ ] Step 3: Return result

Step 0: Check Setup -- BLOCKING

Check EXTEND.md existence and dependencies:

# Check EXTEND.md (priority: project -> user)
test -f .render-mermaid/EXTEND.md && echo "project"
test -f "$HOME/.render-mermaid/EXTEND.md" && echo "user"

# Check dependencies
cd "{SKILL_BASE_DIR}" && npx tsx -e 'Promise.all([import("mermaid"), import("jsdom"), import("puppeteer-core")]).then(() => console.log("deps-ok")).catch(() => { console.log("deps-missing"); process.exit(1); })'

Result	Action
deps-missing	Run bash "{SKILL_BASE_DIR}/scripts/setup.sh" -- BLOCKING
EXTEND.md not found	Run first-time setup (references/config/first-time-setup.md) -- BLOCKING
Both found	Load EXTEND.md, note output_mode value for Step 2 routing, continue

Step 1: Generate Mermaid Source

1. Determine diagram type: flowchart / graph / sequenceDiagram / classDiagram / erDiagram / stateDiagram-v2 / gantt / pie / gitgraph / etc.
2. Generate Mermaid source code.

Step 2: Route and Render

Read output_mode from EXTEND.md to decide rendering path. This is mandatory -- do NOT default to Option A without checking.

output_mode = ?
├── "standalone" ──────────────────→ Option B (always)
├── "script" (or unset) ──────────→ Option A
└── deps missing / setup failed ──→ Fallback (CDN template)

Option A: Script render -- PNG primary (requires Chrome)

cd "{SKILL_BASE_DIR}" && npx tsx scripts/render_mermaid.js \
  --output "<OUTPUT_PATH>.png" \
  --theme "<THEME>" \
  --curve "<CURVE>" \
  --config "<EXTEND_MD_PATH>" \
  --svg-output "<OUTPUT_PATH>.svg" \
  --html-output "<OUTPUT_PATH>.html" <<'MERMAID'
<MERMAID_TEXT>
MERMAID

When only PNG is needed, omit --svg-output and --html-output.

Option B: Script render -- HTML primary (no Chrome needed)

Same script, pass --html-output only (no --output). Uses the official Mermaid renderer and skips PNG/Chrome entirely.

cd "{SKILL_BASE_DIR}" && npx tsx scripts/render_mermaid.js \
  --html-output "<OUTPUT_PATH>.html" \
  --theme "<THEME>" \
  --curve "<CURVE>" \
  --config "<EXTEND_MD_PATH>" <<'MERMAID'
<MERMAID_TEXT>
MERMAID

Optionally add --svg-output for SVG alongside HTML.

Fallback: CDN template (when deps not installed)

Read the template at references/templates/standalone.html, substitute placeholders, and write the output file directly. No script execution needed. Uses Mermaid CDN themes.

Placeholder	EXTEND.md field	Default	Example
{{TITLE}}	-	Mermaid Diagram	Architecture Overview
{{BACKGROUND}}	standalone_background	#ffffff	#1a1a2e
{{MERMAID_CODE}}	-	-	flowchart TD ...
{{MERMAID_THEME}}	standalone_theme	default	dark, neutral, forest
{{MERMAID_CURVE}}	curve	basis	linear, basis, step

Common notes for Option A and B:

Pass --config pointing to the user's EXTEND.md for saved preferences. CLI args override config values.

Use stdin heredoc form to avoid shell escaping issues.

Override rules (take precedence over output_mode):

• User explicitly asks for PNG → Option A regardless of config
• User explicitly asks for HTML → Option B regardless of config
• Deps not installed / setup failed → Fallback (CDN template)

Step 3: Return Result

Script output	Action
RENDER_SUCCESS: <path>	Read PNG, return with 
RENDER_SUCCESS_HTML: <path>	Return HTML path, tell user to open in browser
RENDER_DEGRADED:	Return available outputs (SVG/HTML), explain PNG was unavailable
RENDER_FAILED:	Relay error, correct Mermaid source, retry once
Fallback (CDN)	Return HTML path, tell user to open in browser

Options

Option	Description	Default
--output <path.png>	PNG output (requires Chrome)	-
--svg-output <path.svg>	SVG output	-
--html-output <path.html>	HTML wrapper output	-
--theme <name>	Mermaid official theme	default
--curve <name>	Flowchart curve	basis
--background <color>	HTML/PNG background	theme default
--scale <number>	PNG scale factor	2
--width <number>	Viewport width	2400
--html-padding <px>	HTML padding	40
--chrome-path <path>	Chrome executable	auto-detect
--config <path>	EXTEND.md config file	-
--mermaid <text>	Mermaid text (prefer stdin)	-

Themes

Official Mermaid themes: default, neutral, dark, forest, base.

Flowchart Curves

Supported Mermaid curve values: linear, basis, bumpX, bumpY, cardinal, catmullRom, monotoneX, monotoneY, natural, step, stepAfter, stepBefore.

Full list: references/config/preferences-schema.md

Degradation

Scenario	PNG	SVG	HTML
All working	OK	OK	OK
No Chrome	FAIL	OK	OK
No puppeteer-core	FAIL	OK	OK
No deps	FAIL	FAIL	FAIL

When PNG fails, request --svg-output as fallback.

If all rendering fails, return the Mermaid source code in a fenced code block as final fallback.

Troubleshooting

See references/troubleshooting.md for common issues.

Extension Support

User preferences via EXTEND.md. See Step 0 for paths.

Schema: references/config/preferences-schema.md

References

Config: first-time-setup.md | preferences-schema.md Troubleshooting: troubleshooting.md