markdown-mermaid-writing

Markdown Mermaid Writing Skills

Overview

Markdown Mermaid writing skills are a text-first solution for creating scientific documents, technical reports, and visualization content. By embedding Mermaid diagrams into Markdown documents as standard formats, it enables Git-friendly version control and native rendering.

Use Cases

Scientific papers and scientific reports

Write experimental workflows, data flow diagrams, system architecture diagrams, and timelines. All diagrams are embedded as text in .md files, supporting Git diff comparisons. They can be rendered directly on platforms such as GitHub, GitLab, and Notion.

Technical documentation and software architecture design

Create API sequence diagrams, ER diagrams, state machines, C4 architecture diagrams, and class diagrams. Use 9 document templates (decision records, project documentation, status reports, etc.) and 24 Mermaid diagram types to ensure team documentation standards and consistency.

Project management and visualization needs

Generate Gantt charts, kanban boards, user journey maps, requirement traceability matrices, and project timelines. A text-first approach makes diagrams easy to modify and version, without regenerating images to update content.

Core Features

Support for 24 Mermaid diagram types

Includes flowcharts, sequence diagrams, ER diagrams, state diagrams, Gantt charts, pie charts, mind maps, timelines, class diagrams, radar charts, quadrant charts, requirement diagrams, Sankey diagrams, XY charts, block diagrams, kanban boards, architecture diagrams, user journeys, tree diagrams, dataview diagrams, Git diagrams, ZenUML, and complex combined examples. Each diagram type provides complete styling guidelines, best practices, and copy-paste templates.

Three-stage document workflow

First stage (required): Embed Mermaid in Markdown as the source text.
Second stage (optional): Use Python to generate data charts (matplotlib, seaborn).
Third stage (optional): Use AI to polish and render images.
The text version always remains the true source, ensuring editability and version-control friendliness.

Complete document writing standards and templates

Provides a Markdown style guide (733 lines), a Mermaid style guide (458 lines), and 9 document templates (Pull Request, Issue, kanban, decision record, presentation, research paper, project documentation, tutorial, status report). Includes H1/H2 rules, emoji usage, citation standards, table optimization, and accessibility annotations (accTitle/accDescr).

Frequently Asked Questions

How do I use Mermaid diagrams in Markdown?

In a .md file, create a code block using three backticks and the mermaid tag, then write Mermaid syntax. GitHub, GitLab, VS Code, and most Markdown viewers support native rendering without any build steps. It’s recommended to add accTitle and accDescr for better accessibility.

What diagram types does Mermaid support?

It supports 24 diagram types, including flowcharts, sequence diagrams, ER diagrams, state diagrams, Gantt charts, pie charts, mind maps, timelines, class diagrams, radar charts, quadrant charts, requirement diagrams, Sankey diagrams, XY charts, block diagrams, kanban boards, architecture diagrams, user journeys, tree diagrams, C4 diagrams, dataview diagrams, Git diagrams, ZenUML, and complex combined examples. Each diagram type has dedicated reference files and templates.

Why are text-first documents better for version control?

Text-based diagrams generate readable diffs in Git, making it easy to review change history and collaborate. Image files (PNG, JPG) are binary blobs and cannot show specific changes. Mermaid diagrams, being text, can be parsed by AI tools. They consume fewer tokens than long narrative descriptions and can be converted anytime into high-quality images.