Markdown: Everything You Need and Nothing You Don't

Markdown is one of those things you learn by writing it, then forget the less-common syntax and re-look it up every time. This is the reference you actually need.

The Core Syntax

• # Headings — use 1-6 # signs for h1-h6. Space after # is required.
• **bold** and *italic* — double asterisks for bold, single for italic. _also works_ for italic.
• - Unordered lists — use -, +, or * as bullets. Indent 2-4 spaces for nested lists.
• 1. Ordered lists — numbers followed by period. Numbers don't need to be sequential (1. 1. 1. renders correctly).
• [link text](url) — links. [text](url 'Optional title') adds a tooltip.
•  — images. Alt text is required for accessibility.
• `inline code` — backticks for inline code. Preserves whitespace and disables Markdown inside.
• --- — horizontal rule. Three or more hyphens, asterisks, or underscores.
• > blockquote — prefix lines with > for blockquotes. Nestable with >>.

Code Blocks

Fenced code blocks use triple backticks with optional language for syntax highlighting:

```javascript
const greeting = 'hello';
console.log(greeting);
```

Indented code (4 spaces) also works but is harder to read and doesn't support language syntax highlighting. Always use fenced blocks.

GitHub Flavored Markdown Additions

• Tables: | Col1 | Col2 | / | --- | --- | / | Data | Data |
• Task lists: - [ ] unchecked, - [x] checked. Renders as checkboxes on GitHub.
• Strikethrough: ~~text~~ renders as text with a strikethrough line.
• Autolinks: bare URLs and @mentions auto-link on GitHub.
• Footnotes: text[^1] with [^1]: footnote definition at the bottom.

Documentation Patterns Worth Using

• Start README files with a description, then installation, then quick start example, then full documentation link. The person cloning your repo needs these in order.
• Use admonitions (callout boxes) for warnings: '> **Warning** Be careful of...' Most doc platforms support custom callout styles.
• Code examples should be complete and runnable, not snippets that require context to understand.
• Link to other docs rather than duplicating. A link to the official docs for a dependency is better than a paraphrased version that will become outdated.