markdown

name	markdown
description	Markdown syntax, formatting, and document authoring for docs, READMEs, and technical writing. Use when user mentions "markdown", "write README", "format markdown", "markdown table", "markdown links", "GFM", "GitHub flavored markdown", "markdown linting", "MDX", "markdown to HTML", "table of contents", "markdown badges", "markdown checklist", or authoring documentation in markdown.

Markdown Authoring Reference

Reference for markdown documents covering core syntax, GFM extensions, README patterns, technical docs, MDX, and linting. See references/markdown-guide.md for a syntax cheat sheet and references/tech-writing-guide.md for documentation structure.

1. Core Syntax

Headings

# H1 - Document Title (one per file)
## H2 - Major Section
### H3 - Subsection
#### H4 - Detail Level

Use ATX style (#), not Setext. Space after #. Never skip levels. One H1 per file.

Emphasis and Inline

*italic*    **bold**    ***bold italic***    ~~strikethrough~~
`inline code`    <kbd>Ctrl+C</kbd>    <sup>super</sup>    <sub>sub</sub>

Prefer * over _ -- underscores in some_variable_name cause issues in some parsers.

Links and Images

[Text](https://example.com)                    # inline link
[With title](https://example.com "Hover")      # titled link
[Relative](./docs/setup.md)                    # relative path
[Anchor](#section-name)                        # heading link
![Alt text](./images/screenshot.png)           # image

<!-- Reference-style (cleaner in long docs) -->
See the [guide][contrib] and [CoC][coc].
[contrib]: ./CONTRIBUTING.md
[coc]: ./CODE_OF_CONDUCT.md

Lists

- Item one                    # unordered (use - consistently)
  - Nested (2-space indent)
1. First step                 # ordered
2. Second step
- [x] Done                   # task list (GFM)
- [ ] Pending

Code Blocks

Inline: `npm install`

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

```diff
- const port = 3000;
+ const port = process.env.PORT || 3000;
```

Always specify the language: javascript, typescript, python, bash, json, yaml, sql, html, css, diff.

Blockquotes and Rules

> Blockquote text.
> > Nested quote.

---                           # horizontal rule (blank lines above/below)

2. GitHub Flavored Markdown (GFM)

Tables

| Feature | Free | Pro    | Enterprise |
|---------|------|--------|------------|
| Users   | 5    | 50     | Unlimited  |
| Storage | 1 GB | 10 GB  | 100 GB     |

| Left       | Center     | Right      |
|:-----------|:----------:|------------|
| aligned    | centered   | right      |

Alerts (GitHub)

> [!NOTE]          > [!TIP]           > [!IMPORTANT]
> Info text.       > Advice text.     > Key info.

> [!WARNING]       > [!CAUTION]
> Urgent info.     > Negative consequences.

Footnotes

This needs a source[^1].
[^1]: Source: https://example.com/study

Autolinks and Mentions

https://example.com      <!-- auto-linked -->
@username                <!-- user mention -->
#123                     <!-- issue reference -->
org/repo#456             <!-- cross-repo reference -->

3. Advanced Patterns

Collapsible Sections

<details>
<summary>Click to expand</summary>

Content here (blank line required after summary tag).

</details>

Math / LaTeX

Inline: $E = mc^2$

$$
\frac{n!}{k!(n-k)!} = \binom{n}{k}
$$

Mermaid Diagrams

```mermaid
graph TD
    A[Request] --> B{Auth?}
    B -->|Yes| C[API Gateway]
    B -->|No| D[Login]
    C --> E[(Database)]
```

```mermaid
sequenceDiagram
    Client->>Server: POST /api/users
    Server->>DB: INSERT
    DB-->>Server: OK
    Server-->>Client: 201 Created
```

Table of Contents

## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
  - [CLI](#cli)
  - [API](#api)

Anchor rules: lowercase, spaces become -, strip punctuation. Auto-generate with scripts/markdown-linter.sh (generate_toc function), VS Code "Markdown All in One", or markdown-toc npm package.

4. README Authoring

Badges (shields.io)

![Build](https://img.shields.io/github/actions/workflow/status/owner/repo/ci.yml?branch=main)
![Version](https://img.shields.io/npm/v/package-name)
![License](https://img.shields.io/badge/license-MIT-blue)
![Coverage](https://img.shields.io/codecov/c/github/owner/repo)
![Custom](https://img.shields.io/badge/docs-latest-brightgreen?logo=readthedocs)

Parameters: ?style=flat-square, ?logo=typescript, ?label=custom, ?color=ff6600.

README Template

See examples/markdown-structure.json for a structured template and references/tech-writing-guide.md for guidance. Standard sections in order:

1. Project Name + badges -- one-liner description with build/license/version badges
2. Features -- bullet list of key capabilities
3. Quick Start -- minimal install + usage code block
4. Installation -- detailed prerequisites and setup
5. Usage -- code examples, basic and advanced
6. Configuration -- table of options with types and defaults
7. Contributing -- link to CONTRIBUTING.md
8. License -- license type and link

Project Structure Trees

src/
├── index.ts          # Entry point
├── routes/
│   ├── auth.ts       # Auth routes
│   └── users.ts      # User CRUD
└── utils/
    └── logger.ts     # Logging

Generate with tree -I node_modules, then annotate.

5. Technical Documentation

Follow this hierarchy (detailed in references/tech-writing-guide.md):

1. Overview -- what and why
2. Prerequisites -- tools, versions, access
3. Installation -- step-by-step
4. Quick Start -- minimal working example
5. Detailed Guide -- full walkthrough
6. API Reference -- every public interface
7. Troubleshooting -- common errors and fixes
8. Changelog -- version history

API Endpoint Pattern

### Create User
`POST /api/v1/users`

| Field   | Type   | Required | Description       |
|---------|--------|----------|-------------------|
| `name`  | string | Yes      | Full name         |
| `email` | string | Yes      | Email address     |

**Response (201):**
\`\`\`json
{ "id": "usr_abc123", "name": "Alice", "email": "[e-mail]" }
\`\`\`

6. MDX

MDX combines markdown with JSX for interactive docs (Docusaurus, Nextra, Astro). MDX v2+ uses ESM imports.

import { Button } from '@/components/Button';
import { Callout } from '@/components/Callout';

# Button Component

<Callout type="info">Requires a parent `ThemeProvider`.</Callout>

<Button variant="primary">Click me</Button>

| Prop      | Type                        | Default     |
|-----------|-----------------------------|-------------|
| `variant` | `'primary' \| 'secondary'`  | `'primary'` |
| `size`    | `'sm' \| 'md' \| 'lg'`      | `'md'`      |

7. Markdown Linting

markdownlint

npm install -g markdownlint-cli
markdownlint "**/*.md"
markdownlint --fix "**/*.md"

Configuration (.markdownlint.json):

{
  "MD013": { "line_length": 120 },
  "MD033": false,
  "MD041": true,
  "MD024": { "siblings_only": true }
}

Key rules: MD001 heading increment, MD009 no trailing spaces, MD013 line length, MD024 no duplicate sibling headings, MD033 no inline HTML (disable for <details>/<kbd>), MD041 first line is H1.

remark-lint

npm install remark-cli remark-preset-lint-recommended
npx remark --frail docs/

CI Integration

Use scripts/markdown-linter.sh for local linting. For CI:

- name: Lint Markdown
  uses: DavidAnson/markdownlint-cli2-action@v19
  with:
    globs: '**/*.md'

Use scripts/markdown-stats.py to estimate reading time and word counts.

8. Conversion

pandoc README.md -o README.html              # basic HTML
pandoc README.md -s --toc -o README.html     # standalone with TOC
pandoc README.md -o README.pdf               # PDF (requires LaTeX)
npx marked -i README.md -o README.html       # GFM-compatible

9. Common Mistakes

Mistake	Fix
No blank line before list	Add blank line above
No blank line after heading	Always blank line after
Spaces in URL [text](my url)	URL-encode: %20 or use <url>
Missing language on code fence	Always add: ```python
Mixing * and - for lists	Pick one, stick to it
Wrong nested list indent	2 spaces for unordered, 4 for ordered
--- without blank line above	Becomes Setext heading -- add blank line
Bare URLs	Use <https://url> or [text](url)

Escaping

\*literal asterisks\*   \# not a heading   \| not a table pipe

Characters needing escape: \ ` * _ {} [] () # + - . ! |

10. Editor Setup

VS Code: Markdown All in One (shortcuts, TOC, preview), markdownlint (inline warnings), Markdown Preview Mermaid Support, Paste Image.

Prettier: Add "proseWrap": "always" and "printWidth": 80 in an override for *.md files.