mcpField
D
drawing-mermaid-diagrams

drawing-mermaid-diagrams

github.com/bostonaholicDesign & UI268 installsUpdated today
Repository

About drawing-mermaid-diagrams

A skill for creating Mermaid diagrams that render clearly across documentation and development environments. It covers diagram selection, renderer compatibility, validation, and common syntax pitfalls.

Key features

  1. 01Choose a diagram type suited to the content
  2. 02Account for host Mermaid version differences
  3. 03Render diagrams to validate syntax
  4. 04Check layout and label readability
  5. 05Avoid common Mermaid parsing pitfalls

Use cases

  1. 01Creating diagrams for Markdown documents
  2. 02Preparing diagrams for an unknown renderer
  3. 03Troubleshooting Mermaid rendering errors

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/bostonaholic/skills --skill drawing-mermaid-diagrams

After installing, type/drawing-mermaid-diagramsin Claude Code to confirm it loaded.

Bundled filesagents/openai.yaml

Details

From the project README

Mermaid Diagrams

A diagram is done when it renders without error and its layout reads clearly. Pick the type that matches the content (process, messages, schema, schedule, hierarchy, and so on); a flowchart is not the answer to everything.

Renderer support

  • Each host (GitHub, GitLab, a docs site, an IDE preview) bundles its own Mermaid release, often older than the latest.
  • -beta keywords (xychart-beta, sankey-beta, architecture-beta, block-beta) and recent types such as kanban may fail there.
  • When the target renderer is unknown, prefer a core type, or ask which renderer will display the diagram.

Default to a frontmatter config: block before the diagram keyword. Fall back to a first-line %%{init: {...}}%% directive only for a renderer too old to read frontmatter config.

Validate by rendering

Write the diagram to <out>/diagram.mmd in a scratch directory and render it:

npx -y @mermaid-js/[email protected] -i <out>/diagram.mmd -o <out>/diagram.png

For a Markdown file, -i doc.md -o <out>/doc.md renders every mermaid block. Fix each Parse error on line N or Lexical error and render again until it succeeds. When layout matters, open the PNG and check direction, overlaps, and label text. Only then put the code in its destination.

If mmdc cannot find Chrome, write {"executablePath": "<path to an installed Chrome or Chromium>"} to <out>/puppeteer.json and add -p <out>/puppeteer.json. If Node, network, or a browser is unavailable, do not install one without asking; check the diagram against the gotchas below and tell the user it was not rendered.

A successful CLI render uses the Mermaid release bundled with the CLI, so it does not prove an older host renders the diagram.

Gotchas

Several of these fail silently rather than with a parse error.

  • Labels containing (), [], {}, :, ;, or # are wrapped in "..."; inner quotes are written #quot;, < and > as #lt; and #gt;.
  • A lowercase end as a flowchart node ID or bare label breaks the parse; use End or ["end"].
  • A node ID beginning with o or x right after a link (A---oB) silently becomes a circle or cross edge; add a space or capitalize.
  • %% comments sit on their own line; a trailing comment is a parse error.
  • Block diagrams have no ==> or ::: shorthand.
  • Indentation is significant in mindmap and kanban.
  • Styling not applying: the config block must come first, themeVariables need theme: base, and hex colors in frontmatter must be quoted (an unquoted # is a YAML comment and the color is silently dropped).
  • Renders in the CLI but not on the host: the host's Mermaid is older; replace a -beta or recent type, or switch frontmatter config to %%{init}.

Comments

Markdown supported