alessandrobologna/mermint-markdown-workflow

Mermint Markdown Workflow

Use this workflow to render Markdown Mermaid blocks into GitHub-friendly <picture> markup and SVG assets. Prefer running mermint directly from this GitHub repo with npx; do not assume a local checkout or global install.

Inputs To Confirm

• Target markdown file (example: README.md)
• SVG output directory (example: svgs)
• In-place overwrite vs separate output path
• Whether Mermaid source must be preserved (--keep-mermaid)

Preflight Checks

Before rendering, check:

• node is installed and version >= 22
• npx is available
• network access is available, because the CLI is fetched from GitHub

Example:

node --version
npx --version

Standard Commands

Primary command:

npx --yes git+https://github.com/alessandrobologna/mermint.git \
  --input README.md \
  --svg-dir svgs \
  --keep-mermaid

Use explicit themes when you want stable readme-style output:

npx --yes git+https://github.com/alessandrobologna/mermint.git \
  --input README.md \
  --svg-dir svgs \
  --light-theme default \
  --theme dark \
  --keep-mermaid

For non-interactive in-place conversion (CI/automation), add --yes:

npx --yes git+https://github.com/alessandrobologna/mermint.git \
  --input README.md \
  --svg-dir svgs \
  --keep-mermaid \
  --yes

For a non-destructive preview, write to a separate markdown output:

npx --yes git+https://github.com/alessandrobologna/mermint.git \
  --input README.md \
  --output /tmp/README.rendered.md \
  --svg-dir /tmp/mermint-svgs \
  --keep-mermaid

Frontmatter / Init Conventions

This workflow supports source-level Mermaid config in frontmatter/init, including:

• config.look
• config.fontFamily
• config.architecture.iconPacks
• x-mermint.rough

mermint includes a built-in aws icon pack for Mermaid architecture diagrams. Use aws:<icon> directly without adding a URL or local icon-pack path.

When generating or revising AWS architecture diagrams, read references/aws-architecture-icons.md before inventing icon names. Prefer concrete AWS service icons over generic Mermaid shapes when the service is known. Examples:

• use aws:simple-storage-service for S3-style storage instead of disk
• use aws:dynamodb for DynamoDB-style state instead of database
• use aws:simple-queue-service for SQS instead of a generic queue/storage symbol
• use aws:amazon-simple-notification-service or aws:simple-notification-service for SNS
• fall back to generic Mermaid shapes only when there is no suitable AWS service icon

Use config.architecture.iconPacks only when you need:

• additional non-AWS icon packs
• a local override for the built-in aws pack
• a pinned custom AWS pack snapshot

Optional Hand-Drawn Tuning

Enable hand-drawn rendering with either:

• config.look: handDrawn in frontmatter/init
• --look handDrawn on the CLI

Tune the Rough.js pass with x-mermint.rough in source config, or with CLI flags when you want a one-off override.

Supported rough keys:

• roughness
• fillWeight
• fillStyle
• hachureGap
• hachureAngle
• bowing
• strokeWidth
• seed
• disableMultiStroke
• disableMultiStrokeFill
• preserveVertices

Important behavior:

• rough precedence is CLI > source config > defaults
• --look classic is incompatible with rough overrides
• built-in aws icons work normally in hand-drawn mode
• hand-drawn architecture-beta diagrams with icon references default to fillStyle: solid for icon legibility unless you explicitly set a fill style

Example with AWS icons and source-level Rough.js tuning:

---
config:
  look: handDrawn
x-mermint:
  rough:
    roughness: 0.55
    fillStyle: cross-hatch
    hachureGap: 1
    bowing: 0.8
    seed: 42
---
architecture-beta
  group api(aws:aws-api-gateway)[API Layer]
  service gateway(aws:aws-api-gateway)[API Gateway] in api
  group compute(aws:aws-lambda)[Compute]
  service fn(aws:aws-lambda)[Lambda] in compute
  gateway:R --> L:fn

Equivalent CLI shape for a one-off render:

npx --yes git+https://github.com/alessandrobologna/mermint.git \
  --input README.md \
  --svg-dir svgs \
  --keep-mermaid \
  --look handDrawn \
  --roughness 0.55 \
  --fill-style cross-hatch \
  --hachure-gap 1 \
  --bowing 0.8 \
  --seed 42

AWS Architecture Example

Built-in AWS icons with no extra pack config:

Legibility note:

• if you use hand-drawn mode with architecture icons and do not specify fillStyle, mermint now defaults those diagrams to fillStyle: solid
• set x-mermint.rough.fillStyle or --fill-style explicitly if you want hachure, cross-hatch, or another Rough.js fill style instead

---
config:
  look: handDrawn
---
architecture-beta
  group api(aws:aws-api-gateway)[API Layer]
  service gateway(aws:aws-api-gateway)[API Gateway] in api

  group compute(aws:aws-lambda)[Compute]
  service lambda(aws:aws-lambda)[Lambda] in compute

  group messaging(aws:simple-queue-service)[Messaging]
  service queue(aws:simple-queue-service)[SQS] in messaging

  gateway:R --> L:lambda
  lambda:B --> T:queue

Override the built-in aws pack only when needed:

---
config:
  architecture:
    iconPacks:
      aws: ./aws-architecture-service-icons.json
---
architecture-beta
  service queue(aws:simple-queue-service)[SQS]

If icon packs use relative paths, they resolve from:

• diagram mode: directory of the input .mmd file
• markdown mode: directory of the markdown file

architecture-beta Guardrails

architecture-beta is less predictable than simpler Mermaid diagram types. A render can succeed and still produce an unusable layout.

Prefer these constraints when creating or revising architecture diagrams:

• keep labels short and conservative
• avoid slash-heavy or punctuation-heavy labels unless you render-test them
• avoid decorative edge labels unless they carry essential meaning
• use junction for optional branches or fan-out instead of forcing extra direct edges between services

Recommended optional-branch pattern:

architecture-beta
  service relay(aws:kinesis-data-streams)[Relay]
  junction fanout
  service collector(aws:amazon-opensearch-service)[Collector]
  service archive(aws:simple-storage-service)[Archive]

  relay:R --> L:fanout
  fanout:T --> B:collector
  fanout:B --> T:archive

Fallback rule:

• if architecture-beta still overlaps after one conservative rewrite, stop and either simplify further with a junction-based branch or ask whether to switch to flowchart while preserving the architecture meaning

Verification Checklist

After rendering:

1. Confirm markdown contains <picture> blocks:

rg -n "<picture>" README.md

2. If --keep-mermaid is expected, confirm preserved source blocks:

rg -n "data-mermint-source=\"true\"" README.md

3. Confirm SVG assets exist and are non-empty:

ls -la svgs

4. For architecture-beta, visually inspect at least one rendered SVG or screenshot. A successful render is not enough if labels are unreadable or nodes still overlap.

Failure Recovery

• If node --version is lower than 22, upgrade Node before running mermint.
• If npx is unavailable, install a recent Node.js distribution that includes npm/npx.
• If Playwright browsers are missing:

npx playwright install

• If the error says Executable doesn't exist at .../chromium_headless_shell-<rev>/..., a generic npx playwright install may have installed the wrong browser revision for the Playwright version that mermint resolved.
• In a local checkout, install the headless shell with the exact Playwright version from node_modules instead of relying on an unpinned CLI:

PLAYWRIGHT_VERSION=$(node -p "require('./node_modules/playwright/package.json').version")
npx --yes playwright@$PLAYWRIGHT_VERSION install chromium-headless-shell

• If you are running mermint via npx --yes git+https://github.com/alessandrobologna/mermint.git ... and still hit the same chromium_headless_shell-<rev> error, do not keep retrying an unpinned npx playwright install. Re-run with a version-pinned Playwright CLI or switch to a local checkout long enough to discover the resolved version first.
• If verification uses rg and it is unavailable, use grep instead.
• If rendering fails due to invalid source rough config, fix x-mermint.rough values in source or remove conflicting --look classic.