Markdown Skill

Markdown Expert

Overview

Advanced expertise in Markdown authoring — from technical documentation and README files to specification docs, changelogs, wikis, blog posts, and knowledge bases. Specialized in clean structure, consistent formatting, rich content, and platform-specific Markdown dialects.

Use this skill with /markdown-skill to write, review, restructure, or convert any Markdown content.

1. Markdown Dialects & Platforms

• CommonMark: the universal baseline standard
• GitHub Flavored Markdown (GFM): tables, task lists, strikethrough, autolinks, alerts
• GitLab Flavored Markdown: mermaid diagrams, math, footnotes, table of contents
• Obsidian: wikilinks [[Note]], callouts, embeds, dataview blocks, canvas
• MDX: JSX components inside Markdown for React/Next.js documentation
• Docusaurus / VitePress / MkDocs: admonitions, tabs, code groups, versioned docs
• Notion: block-based Markdown import/export patterns
• Confluence: wiki markup vs Markdown interop
• Pandoc: universal document conversion (Markdown ↔ HTML, PDF, DOCX, LaTeX)

2. Document Structure & Hierarchy

• Heading hierarchy: # H1 (one per doc) → ## H2 → ### H3 (max 3 levels typical)
• Table of contents: manual links vs auto-generated ([[_TOC_]], <!-- toc -->)
• Section ordering: Overview → Prerequisites → Core content → Examples → Reference → FAQ
• Front matter (YAML): title, date, author, tags, description, slug
• Document types: README, CONTRIBUTING, CHANGELOG, ADR, RFCs, runbooks, how-tos
• Navigation design: breadcrumbs, "next/prev" links, related docs

3. Text Formatting

• Bold **text** — emphasis on key terms, warnings, important values
• Italic *text* — titles of works, introducing new terms, soft emphasis
• Strikethrough ~~text~~ — deprecated items, corrections
• Inline code `code` — file names, commands, variables, function names

• Blockquote — callouts, quotes, notes, warnings

• Horizontal rule --- — major section separators
• Avoid overusing bold/italic — reserve for genuine emphasis
• Line length: keep prose under 100 chars for diff-friendly writing

4. Lists

• Unordered lists - — features, options, non-sequential items
• Ordered lists 1. — steps, ranked items, sequential procedures
• Task lists - [ ] / - [x] — checklists, progress tracking (GFM)
• Nested lists: indent with 2 or 4 spaces consistently
• Definition lists (extended Markdown): term + : definition
• Best practices: parallel grammatical structure, avoid mixing list types, use sub-lists sparingly

5. Code Blocks

```language
code here
```

• Always specify language for syntax highlighting: bash, python, typescript, yaml, json, sql, dockerfile, hcl, go, rust, jsx
• Use diff language for showing changes (+ additions, - removals)
• Shell commands: use bash or sh, prefix interactive commands with $
• Long code blocks: add filename comment at top or use code block titles (platform-specific)
• Avoid screenshots of code — always use fenced code blocks

6. Tables

| Column A | Column B | Column C |
|----------|----------|----------|
| value    | value    | value    |

• Alignment: |:---| left, |:---:| center, |---:| right
• Keep tables narrow — split wide tables into multiple focused ones
• Table alternatives: use lists when rows > 10 or cells contain long text
• Caption pattern: bold line directly above the table
• GFM tables don't support multi-line cells — use HTML <table> if needed

7. Links & References

• Inline links: [text](URL) — use for one-off references
• Reference links: [text][ref] + [ref]: URL — use for repeated URLs
• Relative links: [file](./path/to/file.md) — preferred in repos
• Anchor links: [section](#heading-slug) — heading IDs are auto-generated
• Image: ![alt text](path/to/image.png) — always write descriptive alt text
• Badge syntax (shields.io): [![label](badge-url)](link-url)
• Footnotes: text[^1] + [^1]: footnote text (supported in GFM, MDX)

8. GitHub-Specific Features

• Alerts / Admonitions (GFM):

  > [!NOTE]
  > [!TIP]
  > [!IMPORTANT]
  > [!WARNING]
  > [!CAUTION]
  

• Mermaid diagrams: flowchart, sequenceDiagram, gantt, erDiagram, classDiagram
• Math: $inline$ and $$block$$ (GitHub, GitLab, Obsidian)
• Collapsible sections: <details><summary>Title</summary>content</details>
• Keyboard shortcuts: <kbd>Ctrl</kbd>+<kbd>S</kbd>
• HTML inline: use sparingly for features Markdown can't express

9. Document Types & Templates

README

# Project Name
> One-line description

## Features
## Quick Start
## Installation
## Usage
## Configuration
## Contributing
## License

CHANGELOG (Keep a Changelog format)

# Changelog
## [Unreleased]
## [1.2.0] - YYYY-MM-DD
### Added / Changed / Deprecated / Removed / Fixed / Security

Architecture Decision Record (ADR)

# ADR-001: Title
## Status: Accepted
## Context
## Decision
## Consequences

Runbook

# Runbook: Incident Name
## Symptoms
## Diagnosis Steps
## Resolution Steps
## Rollback
## Prevention

How-To Guide

## Overview
## Prerequisites
## Steps
### Step 1: Title
### Step 2: Title
## Verification
## Troubleshooting

10. Writing Quality & Style

• Clarity: one idea per sentence, active voice, concrete nouns
• Scanability: headers every 3-5 paragraphs, bold key terms, short paragraphs
• Completeness: prerequisites stated upfront, examples for every feature
• Consistency: same term for the same concept throughout, consistent casing
• Tone: technical docs → formal and precise; tutorials → friendly and direct
• Avoiding jargon: define acronyms on first use: CI/CD (Continuous Integration/Continuous Delivery)
• Numbers: spell out under ten; use numerals for 10+, measurements, versions
• Code vs prose: use inline code for anything a user would type or copy

11. Markdown Linting & Quality Checks

• markdownlint rules: MD001 heading levels, MD013 line length, MD022 blank lines around headings
• Consistent blank lines: one blank line before/after headings, code blocks, lists
• No trailing spaces (except intentional line break with two spaces)
• No bare URLs — always wrap in angle brackets <url> or use link syntax
• Validate all links: no broken relative paths, no 404 URLs
• Alt text on all images: never empty ![]()
• Ordered list numbering: always use 1. (auto-numbered) for maintainability

Core Competency Summary

• Write clear, well-structured Markdown for any document type
• Apply correct dialect for the target platform (GFM, MDX, Obsidian, etc.)
• Format tables, code blocks, lists, and links with precision
• Author READMEs, changelogs, ADRs, runbooks, how-tos, and API docs
• Embed diagrams (Mermaid), math, and rich media elements
• Review and refactor existing Markdown for structure, clarity, and consistency
• Convert between document formats using Pandoc-compatible patterns
• Enforce linting standards for consistent, maintainable documentation