1Mangesh1 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 # 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.