Markdown & Mermaid

A skill for markdown authoring, Mermaid diagramming, multi-tool visualization, VS Code integration, and cross-platform rendering consistency.

When to Use

Creating technical documentation with diagrams
Choosing the right diagramming tool for your audience
Troubleshooting Mermaid rendering issues
Styling markdown previews in VS Code
Converting unicode escapes to proper emojis
Enterprise documentation with visual standards
Interactive diagrams in VS Code chat (1.109+)

⚠️ MANDATORY: Start Every Diagram With This Template

Do NOT write Mermaid code without this template. Copy-paste first, then customize:

%%{init: {'theme': 'base', 'themeVariables': {'lineColor': '#57606a', 'primaryColor': '#ddf4ff', 'primaryBorderColor': '#0969da', 'primaryTextColor': '#1f2328', 'edgeLabelBackground': '#ffffff'}}}%%
flowchart LR
    A[Input]:::blue --> B[Process]:::purple --> C[Output]:::green

    classDef blue fill:#ddf4ff,color:#0550ae,stroke:#80ccff
    classDef green fill:#d3f5db,color:#1a7f37,stroke:#6fdd8b
    classDef purple fill:#d8b9ff,color:#6639ba,stroke:#bf8aff
    classDef gold fill:#fff8c5,color:#9a6700,stroke:#d4a72c
    classDef red fill:#ffebe9,color:#cf222e,stroke:#f5a3a3
    classDef neutral fill:#eaeef2,color:#24292f,stroke:#d0d7de

    linkStyle default stroke:#57606a,stroke-width:1.5px

Three required components:

Init directive (line 1) — Sets theme, colors, white edge label background
classDef — Semantic colors for all node types
linkStyle default — Gray arrows at 1.5px width

Color Class	Use For	Example
`:::blue`	Input, source, start	`A[Audio]:::blue`
`:::green`	Output, result, data	`C[Transcript]:::green`
`:::purple`	Processing, model	`B[WhisperX]:::purple`
`:::gold`	Decision, condition	`D{Valid?}:::gold`
`:::red`	Error, warning	`E[Failed]:::red`
`:::neutral`	Context, optional	`F[Cache]:::neutral`

Mandatory Workflow: ATACCU

Every Mermaid diagram MUST follow this 6-step protocol. No exceptions — this prevents forgotten palettes, broken layouts, and inconsistent styling.

Step	Action	What to Do
A	Analyze	What data/process am I visualizing? Who is the audience? What diagram type fits?
T	Think	Which layout pattern? (Medallion/Lineage/Pipeline) How many nodes? Will it be too wide/tall?
A	Apply	COPY THE TEMPLATE ABOVE — init directive + classDef + linkStyle. No exceptions.
C	Create	Write the Mermaid code. Every node gets `:::className`. Every flowchart gets `linkStyle default`.
C	Check	Render the diagram. Verify: pastels (not saturated), layout (not lopsided), labels (readable), arrows (gray #57606a).
U	Update	Write the final diagram into the target `.md` file. Add `Figure N: description` label.

Pre-Flight Checklist (Steps A-T-A)

Before writing any Mermaid code, answer these:

□ Diagram type selected (flowchart/sequence/gantt/quadrant/etc.)
□ Layout direction chosen (LR preferred for flow, TD for hierarchy)
□ Subgraph strategy decided (Medallion vs Lineage vs Pipeline)
□ Color assignments mapped (what color = what meaning)
□ Multi-line node labels use <br/> NOT \n

Quality Gate (Steps C-C-U)

After creating the diagram, verify ALL of these:

□ Init directive is FIRST line inside mermaid block
□ edgeLabelBackground is '#ffffff' (white background for edge labels)
□ ALL nodes have style/classDef (no unstyled nodes)
□ Colors are GitHub Pastel v2 (NOT saturated: no #51cf66, #339af0, #fab005)
□ linkStyle default stroke:#57606a,stroke-width:1.5px (flowcharts)
□ Node labels use <br/> for line breaks, NOT \n
□ Diagram rendered and visually inspected
□ No dimension > 3x the other (use subgroups to balance)
□ Figure label added below diagram block
□ Written to target file (not just shown in chat)

Common Violations This Prevents

Violation	ATACCU Step That Catches It
Saturated colors instead of pastels	Apply Skills — load palette first
Missing init directive	Apply Skills — it's step 3
`edgeLabelBackground: 'transparent'` used	Apply Skills — use `'#ffffff'` (white background)
`\n` in node labels (renders as literal text)	Create — use `<br/>` for line breaks
Missing linkStyle	Create — every flowchart needs it
Lopsided layout (7-way fan-out)	Think — choose layout pattern
Diagram only in chat, not in file	Update — write to `.md` file
No figure label	Update — add label

VS Code 1.109+ Native Chat Rendering

VS Code 1.109 introduces native Mermaid rendering in chat via the renderMermaidDiagram tool. This is a deferred tool: call tool_search for "mermaid" to load it before invocation.

When to Use Native Rendering

When creating diagrams in Copilot Chat (not markdown files), use the native tool for:

Interactive exploration: Pan, zoom, and full-screen viewing
Immediate feedback: See diagrams without switching to markdown preview
Iterative refinement: Quick edits with instant re-render
Copy source: Extract the Mermaid code for documentation

Usage Pattern

User: Create a sequence diagram showing OAuth flow

Alex: [uses renderMermaidDiagram tool]
       → Interactive diagram appears in chat
       → User can pan/zoom/fullscreen
       → "Copy source" extracts code for docs

When NOT to Use

Documentation authoring: Use markdown code blocks for .md files
GitHub rendering: Embed Mermaid in markdown for native GitHub support
Presentations: Export to image formats or use D2

Combined Workflow

Design in chat: Use renderMermaidDiagram for rapid iteration
Finalize: Copy the Mermaid source code
Document: Paste into markdown file with ```mermaid code fence

Assets

File	Purpose
`polish-mermaid-setup.prompt.md`	Interactive Mermaid configuration helper

Markdown Preview: Uses VS Code user-level defaults. Optional personal styling belongs in the user profile, not project configuration.

Mermaid Config: Run the "Polish Mermaid Setup" prompt to configure Mermaid rendering for your VS Code environment.

🎯 Diagram Tool Selection Framework

Step 1: Identify Your Communication Goal

What You're Showing	Best Tools	Example Use Cases
Process/Workflow	Mermaid Flowcharts, User Journey	Onboarding, approvals, troubleshooting
System Architecture	Mermaid Flowcharts with subgraphs, D2	Microservices, API design
Relationships	Mermaid ER, Mindmaps, Graphviz	Database schemas, org charts
Time/Sequence	Mermaid Sequence, Gantt	API interactions, timelines
Data/Metrics	Mermaid XY Charts, Sankey, Quadrant	Performance, resource allocation

Step 2: Consider Your Audience

Audience	Primary Goal	Recommended Tools	Style
Executives	Strategic overview	D2, simple flowcharts	Clean, minimal
Architects	Technical accuracy	PlantUML, Mermaid C4	Detailed, precise
Developers	Implementation	Mermaid Sequence, Class	Code-focused
Product Managers	User flows	User Journey, Flowcharts	Business-outcome
Documentation	Learning	All Mermaid types	Progressive disclosure

Step 3: Consider Platform

Platform	Best Tools	Why
GitHub/GitLab	Mermaid	Native rendering, no setup
Confluence/Wiki	Mermaid, PlantUML	Plugin support
VS Code	All tools (extensions)	Live preview
Presentations	D2, simple Mermaid	Executive-friendly

Quick Decision Tree

Need diagram? → What are you showing?
├── Process/Workflow → Mermaid Flowchart
├── System Architecture → Mermaid with subgraphs (or D2 for exec)
├── Relationships → Mermaid ER/Mindmap (or Graphviz for complex)
├── Time/Sequence → Mermaid Sequence/Gantt
└── Data/Metrics → Mermaid XY/Sankey/Quadrant

Companion References

Bulk content moved out of SKILL.md to stay under the 500-line skill-spec ceiling. Load these on demand when the section header below indicates relevance:

markdown-best-practices.md — document structure template, figure/table conventions, Shields.io badges, emoji usage

tool-ecosystem.md — Mermaid / D2 / PlantUML / Excalidraw comparison, VS Code extension setup, syntax examples

diagram-reference.md — diagram types, node shapes, edge styles, color palettes (legacy + GitHub Pastel v2 + Fishbowl), per-diagram theming, classDef, subgraph styling, Gantt + sequence theming, visual design principles

pitfalls.md — parser pitfalls P1–P9, unicode/emoji failures, layout patterns, classDiagram + architecture-beta gotchas, reserved-word handling, cross-diagram compatibility matrix

🔍 Diagram Audit Methodology

When performing comprehensive diagram audits across a project or documentation set, follow this 4-step process:

Step 1: Enumerate

Identify all Mermaid diagrams in the target scope:

# bash/zsh
grep -rl '```mermaid' --include='*.md' | while read f; do echo "$f: $(grep -c '```mermaid' "$f")"; done

# PowerShell
Get-ChildItem -Recurse -Filter "*.md" |
  Select-String -Pattern '```mermaid' |
  Group-Object Path |
  Select-Object Name, Count

Step 2: Categorize

Create an inventory table to track diagram state:

#	File	Diagram Type	Status	Issues
1	README.md	flowchart	⚠️	Missing init
2	arch.md	sequence	✅	None
3	flow.md	flowchart	❌	Parse error

Status codes: ✅ OK, ⚠️ Needs fix, ❌ Broken

Step 3: Batch Fix

Apply fixes in batches by issue type:

Reserved word errors — Rephrase or quote labels
Parse errors — Apply 4 safety rules
Style inconsistencies — Apply GitHub Pastel v2 palette

Step 4: Validate

Re-render all diagrams and confirm fixes:

All diagrams render in VS Code preview
All diagrams render on GitHub
Color palette is consistent
No parse errors in console

Typical results: A 30-40 diagram audit catches 10-15 issues in the first pass.

✅ Quality Checklist

Before Committing

All diagrams have figure labels
All tables have table labels
No unicode escape sequences
Diagrams render correctly in preview AND GitHub
Consistent heading hierarchy
Links are valid

Diagram Review

Node labels are clear and concise (but not over-simplified)
Colors follow consistent palette
Subgraphs logically group related items
Subgraph content is wide enough for title (VS Code)

Don't Over-Simplify

KISS ≠ Remove all detail

KISS means removing unnecessary complexity while preserving meaningful information. If removing detail reduces understanding, keep it.

📚 External References

Official Documentation

VS Code Resources

Visual Design Theory

Tufte, E.R. - The Visual Display of Quantitative Information
Cairo, A. - The Functional Art
Knaflic, C.N. - Storytelling with Data

Mode Fragility Reference

Several Mermaid modes fail silently on colons and special characters. Default to flowchart for arbitrary text content.

Mode	Status	Constraint
`flowchart`	Safe	None — handles any content
`sequenceDiagram`	Safe	Standard message format
`classDiagram`	Safe	Standard notation
`erDiagram`	Safe	Standard notation
`stateDiagram`	Caution	Colons in state names
`journey`	Caution	Score format sensitive
`timeline`	Fragile	No colons in events; `:` is separator
`gitGraph`	Fragile	Long chains with quoted colon-tags break
`gantt`	Fragile	`dateFormat HH:mm` mis-parses task lines

Rule: If your labels contain colons, times (HH:MM), or complex text, use flowchart and structure with subgraphs instead.

Debug silent failures: Check browser console, simplify content, test incrementally, try flowchart — if it works in flowchart, the mode is the problem.

Falsifiability

This skill is wrong if diagrams authored per these patterns fail to render in GitHub or VS Code preview
The syntax guidance is stale if it conflicts with the current Mermaid.js spec (check mermaid.js.org/changelog)
The mode-fragility warnings are not earning tokens if Mermaid resolves the documented rendering bugs in a future release

markdown-mermaid

SKILL.md.github/skills/markdown-mermaid/SKILL.md