Validate Mermaid diagrams in markdown files for syntax errors, configuration, and health score. Uses mcp-mermaid for full validation and local regex for fast pre-checks.
Validates Mermaid diagrams in markdown for syntax, configuration, and rendering health.
/plugin marketplace add https://www.claudepluginhub.com/api/plugins/data-wise-craft/marketplace.json/plugin install data-wise-craft@cpd-data-wise-craftThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Validate Mermaid diagrams in markdown files for syntax errors, text overflow issues, configuration requirements, and health score. Integrates with mcp-mermaid MCP server for full syntax validation and local regex pre-checks for fast CI/pre-commit use.
/craft:docs:check Phase 5)Check that MkDocs is properly configured for enhanced markdown features.
✅ RECOMMENDED: Native Integration (Material for MkDocs)
Per official Material docs, native Mermaid integration requires ONLY the superfences extension:
# Required in mkdocs.yml - Native integration
markdown_extensions:
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
- attr_list # Required for icon attributes { .lg .middle }
- md_in_html # Required for card grids and markdown in HTML
# NO extra_javascript needed - superfences handles it natively!
⚠️ WARNING: Adding extra_javascript CDN can cause conflicts
If you have this in your config, remove it:
extra_javascript:
- https://unpkg.com/mermaid@10/dist/mermaid.min.js # ❌ NOT NEEDED
Material for MkDocs handles Mermaid natively. Adding the CDN manually can cause:
Only add extra_javascript if:
If custom config is needed, use:
extra_javascript:
- javascripts/mermaid-config.js # Your custom config
With javascripts/mermaid-config.js:
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: false, securityLevel: 'loose' });
Common Configuration Issues:
| Missing Extension | Symptom | Fix |
|---|---|---|
custom_fences | Mermaid renders as code blocks | Add superfences custom_fences |
pymdownx.emoji | :rocket: shows as text | Add emoji extension |
attr_list | Icon attributes not working | Add attr_list |
md_in_html | Card grids show as raw text | Add md_in_html |
Material for MkDocs Card Grids:
Card grids require BOTH attr_list AND md_in_html:
<div class="grid cards" markdown>
- :material-rocket:{ .lg .middle } **Title**
Description text
</div>
Without md_in_html, the markdown inside <div> tags won't be processed!
Check for Mermaid overflow CSS in stylesheets:
/* Required for proper rendering */
.mermaid {
overflow-x: auto;
text-align: center;
}
.mermaid svg {
max-width: 100%;
height: auto;
}
.mermaid .nodeLabel {
font-size: 12px !important;
}
Per official Mermaid docs, check each diagram for valid syntax:
Diagram Types:
flowchart, sequenceDiagram, classDiagram, stateDiagram, erDiagramgraph, gantt, pie, journey, gitGraph, mindmap, quadrantChartDirection Keywords:
TB or TD - Top to bottom (recommended for mobile)BT - Bottom to topLR - Left to right (simple linear flows only)RL - Right to leftCritical Syntax Rules:
Reserved "end" keyword - Must capitalize to avoid breaking diagram:
flowchart TD
A[Start] --> B[End] ✅ Capitalized "End"
A[Start] --> B[end] ❌ BREAKS diagram
First letter 'o' or 'x' - Add space or capitalize:
flowchart LR
A --> oNode ❌ Treated as circle edge
A --> O_Node ✅ Capitalize or use underscore
Prefer flowchart over graph - Both work identically, but flowchart is clearer intent
All nodes must be connected - Orphaned nodes cause syntax errors:
flowchart TD
A --> B
C[Orphan] ❌ Not connected to anything
Per official Mermaid docs, use automatic text wrapping instead of manual line breaks.
❌ AVOID: Manual <br/> tags
flowchart TD
A[Getting Started<br/>7 steps] ❌ Manual breaks
B[Intermediate<br/>11 steps]
✅ RECOMMENDED: Markdown strings with automatic wrapping
flowchart TD
A["`**Getting Started**
7 steps · 10 minutes
Essential commands`"] ✅ Auto-wraps, supports markdown
Markdown string syntax (backticks with quotes):
code<br/> tagsText Length Guidelines:
| Element | Max Length | Recommendation |
|---|---|---|
| Node text (single line) | 15-20 chars | Use abbreviations, ... for paths |
| Edge labels | 10 chars | Keep brief |
| Subgraph titles | 20 chars | Short descriptive names |
Examples:
%% BAD: Text too long, will overflow
graph LR
A["~/.git-worktrees/aiterm/feature-mcp/"] --> B
%% GOOD: Abbreviated with markdown string
flowchart LR
A["`**Worktrees**
~/.git-worktrees/
.../feature-mcp`"] --> B["`Next Step`"]
Prefer vertical layouts (TD/TB) over horizontal (LR/RL) for complex diagrams:
| Layout | Best For | Avoid For |
|---|---|---|
flowchart TD | Complex workflows, decision trees, multi-branch flows | - |
flowchart LR | Simple linear flows (< 5 nodes), system architecture | Complex workflows, parallel processes |
Why vertical layouts render better:
Examples:
%% BAD: Horizontal complex diagram
flowchart LR
A --> B --> C --> D
B --> E
C --> F
D --> G
E --> G
F --> G
%% GOOD: Vertical complex diagram
flowchart TD
A --> B --> C --> D
B --> E
C --> F
D --> G
E --> G
F --> G
When to use subgraphs (always with TD):
Report all mermaid diagrams found:
<br/> tags (flag for modernization)When the mcp-mermaid MCP server is available, use it for full syntax validation beyond regex pre-checks:
The MCP server is configured in .mcp.json:
{
"mcpServers": {
"mcp-mermaid": {
"command": "npx",
"args": ["-y", "mcp-mermaid"]
}
}
}
Composite quality metric (0-100) for release gating:
health_score = syntax_validity*0.5 + best_practices*0.3 + rendering_success*0.2
| Score | Level | Release Gate |
|---|---|---|
| >= 90 | Good | Pass |
| >= 80 | Warning | Pass (default threshold) |
| < 80 | Fail | Blocked |
# Automated validation (recommended)
python3 scripts/mermaid-validate.py docs/ commands/ skills/
# With health score
python3 scripts/mermaid-validate.py docs/ --health-score
# Release gate check
python3 scripts/mermaid-validate.py docs/ --gate
# Errors only (fast, for CI)
python3 scripts/mermaid-validate.py docs/ --errors-only
# Auto-fix safe patterns (dry-run)
python3 scripts/mermaid-autofix.py docs/
# Auto-fix (apply changes)
python3 scripts/mermaid-autofix.py docs/ --fix
# Manual grep checks
grep -r "^\`\`\`mermaid" docs/ | wc -l
# Find diagrams using deprecated 'graph' keyword
grep -A1 "^\`\`\`mermaid" docs/**/*.md | grep -c "^graph "
MERMAID DIAGRAM VALIDATION
==========================
Configuration:
✅ custom_fences configured in mkdocs.yml
✅ mermaid.js CDN in extra_javascript
⚠️ No Mermaid CSS found in stylesheets
Diagrams Found: 15 total
docs/guides/GIT-WORKTREES-GUIDE.md: 12 diagrams
docs/architecture/AITERM-ARCHITECTURE.md: 3 diagrams
Syntax Validation:
✅ All 15 diagrams have valid syntax
Text Length Issues:
⚠️ docs/guides/GIT-WORKTREES-GUIDE.md:156
Node text "~/.git-worktrees/aiterm/feature-mcp/" is 38 chars (max 15)
Suggestion: Use "~/.git-worktrees/.../feature-mcp"
Health Score: 92/100 (Good)
Syntax validity: 100.0%
Best practices: 80.0%
Rendering success: 100.0%
Summary:
Passed: 14/15
Warnings: 1 (text length)
Errors: 0 (syntax)
Config: 2/3 (missing CSS)
Release gate: PASS (>= 80)
Recommendations:
1. Add Mermaid CSS to docs/stylesheets/extra.css
2. Shorten node text in GIT-WORKTREES-GUIDE.md line 156
Called by:
/craft:docs:check - Phase 5: Mermaid Validation/craft:site:status --check - Site health check/craft:docs:validate - Documentation validation/craft:check commit - Pre-commit checks/craft:site:deploy - Health score gate (>= 80)Related:
/craft:docs:mermaid - Diagram templates, NL creation, MCP validation/craft:site:status - Quick Mermaid config check/craft:docs:generate - Includes Mermaid guidelinesmermaid-expert agent - MCP-powered diagram generationScripts:
scripts/mermaid-validate.py - Extraction + regex pre-checks + health scorescripts/mermaid-autofix.py - Safe auto-fix engineMCP Server:
mcp-mermaid - Full syntax validation and SVG/PNG renderingPer official Mermaid documentation and Material for MkDocs:
<br/> - Use backtick syntax for multi-line text with auto-wrappingflowchart keyword - Clearer intent than graph (both work identically)mkdocs serve to preview diagrams before deployment%% for documentation within diagrams| Issue | Cause | Fix |
|---|---|---|
| Diagrams show as code | Missing custom_fences | Add superfences to mkdocs.yml |
| Diagram broken ("end" keyword) | Used lowercase "end" | Capitalize to "End" or "END" |
| Orphaned node error | Node not connected | Connect with arrow or remove |
| Text overflows boxes | Using <br/> tags | Switch to markdown strings with backticks |
| Double rendering | Extra_javascript + native | Remove extra_javascript, use native integration |
| Poor mobile rendering | Horizontal (LR) layout | Switch to vertical (TD) layout |
| Theme colors not applied | Using unsupported diagram type | Use flowchart/sequence/class/state/ER only |
| Syntax error on 'o' or 'x' | First letter treated as edge | Capitalize or add space before name |
Activates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.