markdown-mastery

# Markdown Mastery Write expressive, beautifully formatted markdown — from basic documents to complex technical content with diagrams, advanced formatting, and automated tooling. ## Core Principles ### 1. Markdown Is Code — Treat It With Respect Formatting consistency matters. Lint your markdown, format it automatically, keep line lengths reasonable, and use semantic elements correctly. ### 2. Every Element Has a Purpose Don't use bold where a heading belongs. Don't use inline code where a code block is needed. Don't use manual numbering where list numbering works. Semantic markdown is readable markdown. ### 3. Diagrams Are Documentation A Mermaid diagram is worth a thousand words of architectural explanation. Embed diagrams directly in documentation — they version alongside the code and never go out of sync. ### 4. Write for Plain Text First Markdown's superpower is readability in its raw form. Even without a renderer, your document should be scannable and understandable. --- ## Markdown Mastery Maturity Model | Level | Syntax Knowledge | Formatting | Diagrams | Tooling | Complex Documents | |-------|-----------------|------------|----------|---------|-------------------| | **1: Basic** | Bold, italic, links, lists | Inconsistent | None | None | Single flat file | | **2: Intermediate** | Headings, code blocks, tables | Mostly consistent | Basic flowcharts | Manual formatting | Multi-section documents | | **3: Proficient** | Extended syntax, footnotes, task lists | Consistent style | Sequence, state diagrams | Markdown linter | Structured with TOC | | **4: Advanced** | GFM, HTML embedding, custom containers | Linted + auto-formatted | Complex Mermaid (Gantt, class, ERD) | CI pipeline | Multi-file with includes | | **5: Expert** | Obsidian/Notion syntax, MDX, plugins | Programmatic enforcement | Full diagram ecosystem | Custom tooling | Generated documentation portals | **Target**: Level 3 for most developers. Level 4 for technical writers and documentation maintainers. --- ## Actionable Guidance ### Extended Markdown Syntax Reference #### Tables ```markdown | Feature | Basic Markdown | GFM Extended | Notes | |---------|---------------|--------------|-------| | Bold | `**text**` | Same | Use double asterisks | | Italic | `*text*` | Same | Use single asterisks | | Strikethrough | — | `~~text~~` | Not in original spec | | Task List | — | `- [ ] task` | GFM only | | Tables | — | `\| col \| col \|` | GFM only | | Auto-link | — | `<url>` | Angle brackets | | Fenced code blocks | — | ```` ``` ```` | With language tag | | Emoji | — | `:smile:` | GFM renders to emoji | **Alignment in tables:** ```markdown | Left aligned | Center aligned | Right aligned | |:-------------|:--------------:|--------------:| | Left | Center | Right | | Default | `:---:` | `---:` | ``` #### Footnotes ```markdown Here's a statement that needs a footnote[^1]. And another reference to the same footnote[^1]. [^1]: This is the footnote content. It can span multiple lines if you indent the continuation lines. You can even have paragraphs in footnotes. **Rendered as**: Superscript number in text, footnote content at bottom of page. ``` #### Task Lists ```markdown ## Documentation Checklist - [x] Write the README - [x] Add API documentation - [ ] Create contribution guide - [ ] Add code examples - [ ] Verify all links work - [ ] Get peer review ## Status Key - `[x]` = Complete - `[ ]` = Not started - `[-]` = In progress (use `~~[ ]~~` or custom indicator) ``` #### Definition Lists ```markdown While not part of standard markdown, definition lists work in many renderers: Markdown : A lightweight markup language for formatting plain text. GFM : GitHub Flavored Markdown — the extended syntax used on GitHub. Mermaid : A JavaScript-based diagramming and charting tool that renders Markdown-inspired text definitions. ``` #### Subscript and Superscript ```markdown H~2~O is water. <!-- Subscript with ~ --> X^2^ is X squared. <!-- Superscript with ^ --> CO~2~ emissions <!-- Carbon dioxide --> Note: These work in some renderers but not GFM. In GFM, use HTML: H<sub>2</sub>O or X<sup>2</sup> ``` #### Highlight and Keyboard Tags ```markdown ==This text is highlighted== in some renderers. Press <kbd>Ctrl</kbd> + <kbd>C</kbd> to copy. Press <kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> to open command palette. ``` --- ### Mermaid Diagrams Mermaid lets you create diagrams using text definitions that render inline in markdown. Diagrams are version-controlled alongside your code. #### Setup ```bash # Mermaid CLI (for rendering locally) npm install -g @mermaid-js/mermaid-cli # Render a mermaid file npx mmdc -i diagram.mmd -o diagram.png # VS Code extension: "Markdown Preview Mermaid Support" # GitHub: Mermaid supported natively in Markdown files # GitLab: Mermaid supported in Markdown blocks # Notion: Mermaid support via `/mermaid` command ``` #### Flowcharts ```markdown ```mermaid flowchart LR A[Start] --> B{Is it working?} B -->|Yes| C[Great!] B -->|No| D[Debug] D --> E[Fix the issue] E --> B C --> F[End] style A fill:#4CAF50,color:#fff style C fill:#4CAF50,color:#fff style D fill:#ff9800,color:#fff style E fill:#2196F3,color:#fff ``` **Syntax:** ```text flowchart <orientation> <node_id>[<label>] --> <node_id>{<label>} Orientations: LR (left-right), RL (right-left), TB (top-bottom), BT (bottom-top) Node shapes: [text] - Rectangle (text) - Rounded rectangle {text} - Diamond (decision) [[text]] - Subroutine >text] - Asymmetric (((text))) - Double circle ``` #### Sequence Diagrams ```markdown ```mermaid sequenceDiagram participant User participant Frontend participant API participant Database User->>Frontend: Submit Order Frontend->>API: POST /orders API->>Database: Insert order Database-->>API: Order created API-->>Frontend: 201 Created Frontend-->>User: Order confirmed rect rgb(200, 220, 250) Note over API,Database: Payment Processing API->>Database: Update status end ``` **Syntax:** ```text sequenceDiagram participant <name> actor <name> - Person icon <actor>->><actor>: Solid line (request) <actor--><actor>: Dashed line (response) Note over <actor>,<actor>: <text> rect rgb(r, g, b) ... group ... end ``` #### Gantt Charts ```markdown ```mermaid gantt title Project Timeline - Q1 2024 dateFormat YYYY-MM-DD axisFormat %b %d section Planning Requirements :done, r1, 2024-01-01, 2024-01-14 Design Review :done, r2, 2024-01-10, 2024-01-20 section Development Frontend :active, dev1, 2024-01-15, 2024-02-15 Backend : dev2, 2024-01-20, 2024-02-20 API Integration : dev3, 2024-02-01, 2024-02-25 section Testing Unit Tests : test1, 2024-02-15, 2024-03-01 Integration Tests : test2, 2024-02-20, 2024-03-05 UAT : test3, 2024-03-01, 2024-03-15 section Launch Deployment :milestone, launch, 2024-03-15, 0d ``` **Status indicators:** - `done` — Completed (filled bar) - `active` — In progress (hatched bar) - `crit` — Critical path (red border) - `milestone` — Single-day milestone (diamond) - Default — Planned (empty bar) #### Class Diagrams ```markdown ```mermaid classDiagram class Animal { +String name +int age +makeSound() void +move() void } class Dog { +String breed +fetch() void +bark() void } class Cat { +String furColor +purr() void +scratch() void } class Zoo { -List~Animal~ animals +addAnimal(Animal a) void +getAnimals() List~Animal~ } Animal <|-- Dog Animal <|-- Cat Zoo "1" --> "*" Animal %% Relationships: %% <|-- : Inheritance %% *-- : Composition %% o-- : Aggregation %% --> : Association %% ..> : Dependency %% -- : Link (solid) %% .. : Link (dashed) ``` **Visibility modifiers:** - `+` Public - `-` Private - `#` Protected - `~` Package/Internal #### Entity-Relationship Diagrams (ERD) ```markdown ```mermaid erDiagram CUSTOMER ||--o{ ORDER : places ORDER ||--|{ LINE_ITEM : contains PRODUCT ||--o{ LINE_ITEM : "appears in" CUSTOMER { int id PK string name string email datetime created_at } ORDER { int id PK int customer_id FK datetime order_date string status decimal total } LINE_ITEM { int id PK int order_id FK int product_id FK int quantity decimal unit_price } PRODUCT { int id PK string name string description decimal price int stock_quantity } ``` **Relationship cardinality:** - `||--||` : One-to-one - `||--o{` : One-to-many (optional) - `||--|{` : One-to-many (required) - `}o--o{` : Many-to-many (optional) - `}|--|{` : Many-to-many (required) #### State Diagrams ```markdown ```mermaid stateDiagram-v2 [*] --> Draft Draft --> Review: Submit Review --> Draft: Request changes Review --> Approved: Approve Approved --> Published: Publish Published --> Archived: Auto-archive (30 days) Archived --> [*] note right of Draft Initial document state Author can edit freely end note note right of Published Visible to all users Creates backup on publish end note ``` #### Pie Charts ```markdown ```mermaid pie title Programming Language Usage (2024) "JavaScript" : 32 "Python" : 28 "TypeScript" : 18 "Go" : 10 "Rust" : 7 "Other" : 5 ``` #### User Journey Maps ```markdown ```mermaid journey title User Onboarding Journey section Sign Up Visit landing page: 5: User Create account: 4: User Verify email: 3: User, System section First Experience Complete profile: 4: User Take tutorial: 5: User Explore features: 4: User section Value First action: 5: User, System See results: 5: User ``` #### Git Graph ```markdown ```mermaid gitGraph commit id: "Initial commit" commit id: "Add project setup" branch develop checkout develop commit id: "Add feature A" commit id: "Add feature B" branch feature/cool-new-feature checkout feature/cool-new-feature commit id: "WIP: work in progress" commit id: "Complete feature" checkout develop merge feature/cool-new-feature checkout main merge develop tag: "v1.0.0" commit id: "Hotfix" branch release/v1.1.0 checkout release/v1.1.0 commit id: "Release prep" ``` --- ### GitHub-Flavored Markdown (GFM) Specifics #### Mentioning Users and Teams ```markdown @username — Mentions a user @org/team-name — Mentions a team (notifies all members) <!-- Examples --> @octocat Can you review this PR? @acme/security-team Please review the security implications.