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": "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              # 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.