Pretty Mermaid renders diagrams without a browser, and packages the result as an agent skill
AI Agent Skill to generate and render beautiful Mermaid diagrams as SVG or terminal ASCII — 15 themes, 6 diagram types, batch CLI, no browser.
At a glance
- What is it?
- Pretty Mermaid is an MIT-licensed Node.js skill that turns Mermaid source into themed SVG, PNG, or terminal ASCII. Its selling point is what it does not need: Chromium, Puppeteer, or a DOM.
- Who is it for?
- Adopt Pretty Mermaid if your diagrams are generated inside an agent session or a CI job where installing a headless browser is the expensive part, and if flowchart, sequence, state, class, ER and XY charts cover what you draw. Do not adopt it if you need Mermaid features outside those six types, or if you want the full upstream Mermaid renderer with its plugin ecosystem behind the output.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 24 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem is the browser, not the diagram syntax
Mermaid already solves diagram authoring. You write text, you get a diagram. The friction starts when the diagram has to leave the editor. The common path runs Mermaid through a headless browser, which means a Chromium download, a Puppeteer or Playwright dependency, and a render step that behaves differently on a laptop than in a container. For a documentation pipeline that is a lot of moving parts for something that produces a static file.
Pretty Mermaid targets that gap. The README states it renders locally without Chromium, Puppeteer, or a DOM, and that PNG output is produced directly in Node.js with no external converter. The second claim is the more interesting one, because SVG generation in pure JavaScript is a solved problem while rasterising it usually is not.
The audience is narrow and specific. This is packaged as an agent skill, installed through the skills.sh CLI, and the README lists Claude Code, Cursor, Gemini CLI, Antigravity, OpenCode, Codex and qoder as supported environments. The intended user is someone whose coding agent produces a diagram mid-conversation and needs a file on disk, not someone who maintains a hand-drawn architecture diagram in a wiki.
What the render pipeline actually produces
The repository describes three output formats from one Mermaid source: SVG for documentation, PNG for sharing, and ASCII or Unicode for terminals. The README also mentions ANSI-colored terminal output, which is a different thing from plain ASCII and suggests the terminal path emits escape sequences rather than a grid of characters. Both are listed, and the documentation does not spell out when you get which.
Six diagram types are supported: flowchart, sequence, state, class, ER, and XY charts. That is a deliberate subset of Mermaid's full grammar, and the README does not claim otherwise. If you write a Gantt chart, a pie chart, a git graph, or a mind map, nothing in the supplied material says those will render.
The theme set is 15 entries, split into light, dark, and a third group. The named light themes are zinc-light, tokyo-night-light, catppuccin-latte, github-light, and solarized-light. The dark list is zinc-dark, tokyo-night, tokyo-night-storm, catppuccin-mocha, github-dark, and solarized-dark. The remaining group is nord, nord-light, dracula, and one-dark. The README points to a 15-theme gallery in docs/THEME_GALLERY.md that shows the same flowchart rendered across every theme, which is the right way to present this: theme choice is visual, and a list of names tells you nothing.
The renderer also supports custom colors, CJK state names, multiline labels, linkStyle, and configurable ELK layout spacing, according to the README. ELK is the layout engine that handles graph arrangement, so exposing its spacing is a real knob for dense diagrams. XY chart tooltips are described as interactive, which only makes sense in the SVG output.
Installing it as a skill, and the commands you actually type
Installation goes through the skills CLI rather than npm:
npx skills add imxv/pretty-mermaid-skills@pretty-mermaid -g -y
The -g flag installs globally and -y skips the confirmation prompt. Verification is a separate command, npx skills list -g, and the README says to confirm that pretty-mermaid appears in the global skill list. Node.js 16 or newer is the only stated requirement.
Once installed, the scripts are invoked directly with node. Listing themes is node scripts/themes.mjs. A single render takes an input file, an output path, and a theme:
node scripts/render.mjs --input diagram.mmd --output output.svg --theme tokyo-night
PNG adds a --format flag and a width: --format png --width 1200. Batch mode swaps the single input for a directory pair, --input-dir ./diagrams --output-dir ./output, and takes the same --theme argument.
That flag surface is small enough to memorise, which is the point. There is no config file documented in the supplied material, so theme and format selection happen per invocation. For a repository with a house style, that means either a wrapper script or repeating the theme flag in every call. The README does not describe a way to set a default theme once.
Where the skill framing helps and where it constrains you
Packaging this as an agent skill rather than a library changes who calls it. The agent reads SKILL.md, decides a diagram is wanted, and shells out to scripts/render.mjs. The output lands as a file the agent can then reference. That is a cleaner loop than asking a model to emit SVG markup directly, which tends to produce coordinates that overlap.
The constraint is that the skill interface is the documented interface. The README links a beautiful-mermaid API reference at references/api_reference.md and notes the project is based on beautiful-mermaid by lukilabs, so a programmatic surface exists upstream. But this repository's own documentation is written around the CLI scripts and the skill entry point. If you want to call the renderer from your own Node process, the supplied material does not show the import path or the function signatures. You would be reading the API reference and the source.
There is also a distribution question. Installing through npx skills add ties the project to that CLI's conventions and to a global skill directory. A team that already vendors its tooling through package.json gets a second install mechanism to track. The MIT licence removes any legal obstacle to copying the scripts into your own repo, which is probably the pragmatic answer for a CI pipeline.
The failure mode is diagram coverage, not rendering quality
The honest limitation here is scope. Six diagram types is a real ceiling, and Mermaid users do not stay inside it. The moment a document needs a timeline, a quadrant chart, or a requirement diagram, this tool has nothing to say, and the fallback is the browser-based path you were trying to avoid. The README's own example set is six .mmd files in assets/example_diagrams/, one per supported type, which is consistent with that boundary being deliberate rather than an oversight.
The second limitation is that claims about CJK state names, multiline labels, linkStyle, and ELK spacing are not backed by examples in the supplied material. Those are exactly the features that break in a hand-rolled renderer, because they stress text measurement and layout rather than path drawing. The README asserts support; it does not demonstrate it in the example files. Treat those as things to verify on your own diagrams.
Third, there are no releases retrieved for this repository. The last push is dated 2026-08-22 and the README links a CHANGELOG.md and a RELEASING.md, so a release process is documented, but the supplied material contains no version numbers. Pinning to a commit is the only reproducible option until you check the changelog yourself.
Compared with running Mermaid through a headless browser
The obvious alternative is Mermaid's own CLI or the mermaid npm package driven by Puppeteer or Playwright. That path renders with the upstream implementation, so it supports the full diagram grammar and tracks Mermaid releases. The cost is the browser: a Chromium binary in your image, a larger dependency tree, and a render step that needs a sandbox or the right flags in a container.
Pretty Mermaid inverts those trade-offs. You give up grammar coverage and upstream parity, and in exchange the render is a plain Node process with no browser. For an agent that renders one diagram mid-session, or a CI job that already runs on Node, that is a favourable trade. For a documentation site that renders hundreds of diagrams from varied sources, the coverage ceiling will bite.
A second alternative is not rendering at all: commit the .mmd files and let the consuming platform draw them. GitHub renders Mermaid in Markdown, and many docs frameworks do the same. That works until you need a PNG for a slide, a themed SVG that matches your site, or output inside a terminal where no renderer exists. Pretty Mermaid's ASCII and ANSI modes are aimed squarely at that last case, and no browser-based tool covers it.
Licence, maintenance and what you are signing up for
The project is MIT licensed, which permits commercial use, modification, and redistribution provided the copyright notice and permission notice are retained. Since it is described as based on beautiful-mermaid by lukilabs, the upstream project's licence is worth confirming before you redistribute anything, because the acknowledgement in the README is not the same as a licence statement. This is not legal advice; check both LICENSE files if you plan to vendor the code.
Maintenance cost is low by construction. The dependency surface is Node 16 and up, with no browser toolchain to patch. The risk sits in the Mermaid grammar: as upstream Mermaid adds diagram types, this renderer does not automatically gain them, and the gap widens over time. The README's references directory includes a diagram syntax reference and a theme reference, so the supported subset is documented rather than implied.
Upgrades are manual. There are no retrieved releases, so there is no version to bump against. If you vendor the scripts, you own the diff when you pull changes from main. If you install through the skills CLI, npx skills add is your update path, and the README does not describe an upgrade command distinct from install.
Editorial conclusion
Adopt Pretty Mermaid if your diagrams are generated inside an agent session or a CI job where installing a headless browser is the expensive part, and if flowchart, sequence, state, class, ER and XY charts cover what you draw. Do not adopt it if you need Mermaid features outside those six types, or if you want the full upstream Mermaid renderer with its plugin ecosystem behind the output. Before committing, render one real diagram of yours at the theme you intend to ship and open the SVG in the viewer your readers actually use; the README states CJK state names, multiline labels, linkStyle and configurable ELK layout spacing are supported, so test those specific features if you depend on them, since none of them are demonstrated in the repository's own example files.
Community notes