allenyllee/mermaid-hq-png-export

Mermaid HQ PNG Export

Workflow

1. On install or first use, bootstrap the pinned local dependencies:

python3 scripts/bootstrap_renderer_env.py

2. Save Mermaid text to a .mmd file.
3. Choose backend by intent:
   • If the user wants a high-resolution PNG, prefer mmdc first, then kroki-local.
   • Use kroki only when the user explicitly asks for Kroki output or Kroki compatibility.
   • If using kroki, tell the user that remote PNG size is fixed and --scale will not change it.
4. Run scripts/render_mermaid_png.py to render PNG natively from SVG.
5. Return the output path and rendered pixel size.

Use this command:

python3 scripts/render_mermaid_png.py \
  --input /abs/path/diagram.mmd \
  --output /abs/path/diagram-4x.png \
  --scale 4

Batch mode:

python3 scripts/render_mermaid_png.py \
  --batch-dir /abs/path/mermaid-files \
  --output-dir /abs/path/png-output \
  --pattern '*.mmd' \
  --recursive \
  --scale 4

Why This Works

• Default to mmdc for PNG output so flowchart labels are preserved.
• Add kroki-local, a local CLI/backend that targets Kroki-like Mermaid output.
• Bootstrap and pin local dependencies under ~/.local/mermaid-hq-png-export.
• Keep renderer-side auto-install as a fallback, not the primary installation mechanism.
• auto fallback order is mmdc -> kroki-local -> kroki.
• For high-resolution requests, prefer mmdc or kroki-local; do not choose remote kroki unless the user specifically wants Kroki output.
• Do not inject flowchart.htmlLabels=false by default; it breaks HTML-styled labels in tested block-beta cases.

Requirements

• Runtime:
  • For default mmdc: no preinstalled mmdc required (script auto-installs).
    • On Windows, the renderer detects mmdc.cmd and other Windows-specific executable names automatically.
  • For kroki-local: prefer local Chromium/Chrome, but bundled browser fallback is supported.
    • If local Chrome/Chromium is found, use it with puppeteer-core.
    • If local Chrome/Chromium is not found, install puppeteer and use its bundled browser.
    • On Windows, common Edge and Chrome install paths are checked automatically before bundled-browser fallback.
  • For kroki fallback/path: curl and network access to https://kroki.io.
    • The current kroki path fetches PNG directly from remote Kroki.
    • If --keep-svg is requested, the renderer fetches remote SVG separately and saves it locally.
    • --scale does not change remote Kroki PNG size; the renderer warns when backend=kroki is used with a scale other than 1.
• Auto-install dependencies:
  • curl and tar are needed if Node.js must be downloaded automatically.
  • scripts/bootstrap_renderer_env.py installs the expected local toolchain up front and verifies the installed versions.
  • kroki-local packages are installed locally under ~/.local/mermaid-hq-png-export/kroki-mermaid-local-cli.
  • kroki-local pins Mermaid 11.12.3, and regression tests verify the installed version matches.
  • Regression tests also verify that kroki-local is using either the expected puppeteer-core version or the expected puppeteer version.

Regression Tests

Run regression tests from the skill root:

python3 tests/run_regression_tests.py

Expected behavior:

• mmdc_flowchart_text: PASS
• kroki_flowchart_text: PASS
• kroki_local_flowchart_text: PASS
• kroki_local_block_beta_geometry: PASS

Troubleshooting

• If local Chromium sandbox blocks mmdc in restricted environments, run outside sandbox or with compatible Chromium flags.
• If backend=kroki-local cannot start, set MERMAID_SKILL_CHROME to your Chromium/Chrome path.
• On Windows, PowerShell execution policy can block npm.ps1; the renderer prefers npm.cmd automatically, so no execution-policy change should be required.
• If mmdc install fails and Kroki is unavailable, install Node.js + @mermaid-js/mermaid-cli manually.
• If text still disappears, verify the SVG contains <text> nodes, not only <foreignObject>.
• If output is too large/small, change --scale.

Implementation Notes

• kroki-local keeps a Kroki-style Mermaid SVG path, but PNG output uses browser screenshot instead of ffmpeg.
• This change was chosen after verifying that serializer-only normalization does not fix flowchart labels when SVG still contains foreignObject.
• HTML-styled label regressions are covered in tests for both flowchart and block-beta.
• kroki-local Mermaid is pinned to 11.12.3 because it stays closer to current Kroki layout than 11.13.0 in the tested block-beta case.