skills.rest
exception-coder
exception-coderCOMMUNITY
Explore all skills by this author →
GitHub

markdown-writing-standards

Validate Mermaid diagrams and Markdown structures to prevent rendering errors.

6|1|Updated Mar 30, 2026
Search Tags:#documentation#markdown#mermaid#lint#tables#diagram-validation
One-click install
npx skills add https://github.com/exception-coder/team-standards --skill markdown-writing-standards
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: markdown-writing-standards
Source: https://github.com/exception-coder/team-standards/tree/main/skills/markdown-writing-standards
Command: npx skills add https://github.com/exception-coder/team-standards --skill markdown-writing-standards

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Prevents broken or misrendered Mermaid diagrams and inconsistent Markdown structure by enforcing a concise set of syntactic and stylistic rules so diagrams and tables render reliably across tools and avoid time-consuming fixes.

Core Features & Use Cases

  • Mermaid safety rules: bans emoji, requires quoting for special characters, enforces node ID formats, controls <br/> usage, and provides per-diagram self-checklists to eliminate render errors.
  • Structured Markdown guidance: enforces table, code block, and heading conventions to keep documentation consistent and machine-friendly.
  • Use Case: validate design docs, bug-call chains, sequence/state/class diagrams, and project docs before committing or publishing to ensure compatibility across GitHub, GitLab, and editors.

Quick Start

Run the markdown-writing-standards check on your draft to validate Mermaid blocks, tables, and code blocks and fix any violations before saving the file.

Frequently Asked Questions about markdown-writing-standards

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why does my Mermaid diagram fail to render in GitHub or GitLab?▼

Mermaid diagrams fail to render due to syntax errors like unquoted special characters, invalid node IDs, or banned emojis. Validating Mermaid syntax against strict formatting rules before committing prevents these rendering errors across platforms.

How do I validate Markdown tables and code blocks for consistent formatting?▼

To validate Markdown tables and code blocks, apply structural linting rules that enforce table, code block, and heading conventions. This ensures documentation remains consistent and machine-friendly before publishing or saving files.

What is the best way to prevent parsing errors in sequence and state diagrams?▼

The best way to prevent parsing errors in sequence and state diagrams is using a pre-write self-checklist that restricts <br/> usage and enforces node ID constraints. This eliminates diagram validation failures before they reach production.

Can I use emojis in Mermaid diagrams without breaking the rendering?▼

No, emojis are prohibited in Mermaid diagrams because they cause rendering errors. You must quote special characters and follow node ID constraints to ensure diagrams render reliably across GitHub, GitLab, and editors.

How do I check structured design and bug documents before committing?▼

To check structured design and bug documents before committing, run a validation pass on Markdown structures and Mermaid blocks. This enforces formatting conventions and fixes any violations before saving the file.

Related Skills

Explore More Content & Communication Skills→
JNZaderJNZader

mermaid-validate

Validate Mermaid diagram syntax in Markdown files and directories.

Community
Intermediate
copilot-ldcopilot-ld
1

libdoc

Render Markdown documentation into static HTML sites with Mustache templates.

Official
Advanced
mcj-codermcj-coder
1

documentation-as-code

Lint, spell-check, and validate links in Markdown documentation files.

Community
Intermediate
bresendsbresends

lint-markdown

Lint and fix Markdown files using markdownlint-cli2.

Community
Intermediate