# Markdown Skill > Markdown Expert - Skill: `sirhamza/markdown-skill` (Agent Skill) - Install (CLI): `npx skillmds@latest add sirhamza/markdown-skill` - Raw SKILL.md: https://api.skillmd.com/api/skills/sirhamza/markdown-skill/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: SirHamza (https://skillmd.com/u/sirhamza) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/sirhamza/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_]]`, ``) - 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 ````markdown ```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 ```markdown | 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 `` 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): ```markdown > [!NOTE] > [!TIP] > [!IMPORTANT] > [!WARNING] > [!CAUTION] ``` - **Mermaid diagrams**: flowchart, sequenceDiagram, gantt, erDiagram, classDiagram - **Math**: `$inline$` and `$$block$$` (GitHub, GitLab, Obsidian) - **Collapsible sections**: `
Titlecontent
` - **Keyboard shortcuts**: `Ctrl+S` - **HTML inline**: use sparingly for features Markdown can't express --- ## 9. Document Types & Templates ### README ```markdown # Project Name > One-line description ## Features ## Quick Start ## Installation ## Usage ## Configuration ## Contributing ## License ``` ### CHANGELOG (Keep a Changelog format) ```markdown # Changelog ## [Unreleased] ## [1.2.0] - YYYY-MM-DD ### Added / Changed / Deprecated / Removed / Fixed / Security ``` ### Architecture Decision Record (ADR) ```markdown # ADR-001: Title ## Status: Accepted ## Context ## Decision ## Consequences ``` ### Runbook ```markdown # Runbook: Incident Name ## Symptoms ## Diagnosis Steps ## Resolution Steps ## Rollback ## Prevention ``` ### How-To Guide ```markdown ## 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 `` 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