| 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
 # 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)
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:
- Project Name + badges -- one-liner description with build/license/version badges
- Features -- bullet list of key capabilities
- Quick Start -- minimal install + usage code block
- Installation -- detailed prerequisites and setup
- Usage -- code examples, basic and advanced
- Configuration -- table of options with types and defaults
- Contributing -- link to CONTRIBUTING.md
- 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):
- Overview -- what and why
- Prerequisites -- tools, versions, access
- Installation -- step-by-step
- Quick Start -- minimal working example
- Detailed Guide -- full walkthrough
- API Reference -- every public interface
- Troubleshooting -- common errors and fixes
- 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": "alice@example.com" }
\`\`\`
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
pandoc README.md -s --toc -o README.html
pandoc README.md -o README.pdf
npx marked -i README.md -o README.html
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.
