# Pretty Mermaid

> Render explicit Mermaid/.mmd, terminal ASCII, or compact static diagrams with editable source. Use Archify for graphical architecture and workflow maps.

- Skill: `jialuohu/pretty-mermaid` (Agent Skill, multi-file: 25 files)
- Install (CLI): `npx skillmds@latest add jialuohu/pretty-mermaid`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jialuohu/pretty-mermaid/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: jialuohu (https://skillmd.com/u/jialuohu)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jialuohu/pretty-mermaid

---


# Pretty Mermaid

Use this skill whenever Mermaid is the chosen format, including explicit
Mermaid or `.mmd`, terminal ASCII, and compact static diagrams. Save Mermaid
source before rendering. Keep an existing `.mmd` file unchanged unless the
user asks to edit it, and place new source beside its export.
Exports retain editable `.mmd` source and use self-contained SVG, genuine PNG,
or rendered ASCII as requested.

## Workflow

1. Run `pretty-mermaid doctor --json`. If the launcher is unavailable, resolve this skill directory and run `node scripts/pretty-mermaid.mjs doctor --json`.
2. If the runtime is missing or incompatible, use native inline Mermaid with the unchanged source, briefly disclose the fallback, and report the setup command from the doctor result. Do not install packages during an ordinary render.
3. Create or validate the `.mmd` source. Use quoted node labels when labels contain punctuation or parentheses. If the user gave no destination, create a task-scoped temporary directory with `mktemp -d` and keep the source and export there; do not add automatic artifacts to the active repository.
4. On a graphical surface, default to SVG and the renderer's default theme (`github-light` when available). In a terminal, render ASCII and include the editable `.mmd`. Honor an explicit destination, format, theme, color, scale, or transparency setting.
5. Render the artifact, for example:

   ```bash
   pretty-mermaid render \
     --input /absolute/path/diagram.mmd \
     --output /absolute/path/diagram.svg \
     --format svg \
     --theme github-light
   ```

6. For PNG, default to `--scale 2` unless the user requests another scale. For terminal output, use `--format ascii`; add `--use-ascii` only when Unicode box drawing is unsuitable.
7. Verify the output exists. Display SVG or PNG using its absolute path in the final response and link the `.mmd` source. For ASCII, include the rendered text and the `.mmd` path.

## Selection Rules

- Explicit application choice takes precedence, followed by the existing artifact format. Use `$omnigraffle-workflow` for OmniGraffle or `.graffle`.

- Use this skill by default whenever Mermaid is selected, including quick explanations,
  compact static relationships, and architecture or workflow content that the
  user explicitly wants in Mermaid.
- Use `$archify` as the graphical default for architecture and workflow maps,
  and for polished interactive sequence, data-flow, or lifecycle artifacts.
- Use native inline Mermaid only when the user explicitly requests it or when the runtime is unavailable or rejects the syntax. Briefly disclose automatic fallback, reuse the exact source, and do not silently change semantics.
- Use `$drawio` for explicit draw.io or diagrams.net requests, editable `.drawio` source, multi-page files, specialized shapes, browser editing, or draw.io Desktop exports.
- Use `$paper-figure-workflow` for reproducible publication figure pipelines; it delegates native execution to the selected application owner.
- Use bundled Visualize for adjustable, inspectable, in-conversation spatial
  views rather than a standalone static export.
- Beautiful Mermaid implements a Mermaid subset. Run `capabilities` when syntax support is uncertain. If rendering rejects a diagram family, preserve the `.mmd`, fall back to native inline Mermaid, and report the limitation.

## Commands

```text
pretty-mermaid render --input FILE --format svg|png|ascii [--output FILE]
pretty-mermaid batch --input-dir DIR --output-dir DIR --format svg|png|ascii
pretty-mermaid themes [--json]
pretty-mermaid capabilities [--json]
pretty-mermaid doctor [--json]
pretty-mermaid update [--strict]
pretty-mermaid rollback
```

The toolbox setup installs `pretty-mermaid` into `CODEX_LOCAL_BIN_DIR` (default `~/.local/bin`). When that directory is not on `PATH`, run the equivalent `node scripts/pretty-mermaid.mjs ...` command from this skill directory. Read `references/cli.md` for complete flags, exit behavior, and runtime recovery.