Markdown

## Whitespace Traps - Blank line required before lists, code blocks, and blockquotes—without it, many parsers continue the previous paragraph - Nested lists need 4 spaces (not 2) for GitHub/CommonMark; 2 spaces breaks nesting in strict parsers - Two trailing spaces for `<br>` break—invisible and often stripped by editors; prefer blank line or `<br>` tag - Lines with only spaces still break paragraphs—trim trailing whitespace ## Links & Images - Parentheses in URLs break `[text](url)`—use `%28` `%29` or angle brackets: `[text](<url with (parens)>)` - Spaces in URLs need `%20` or angle bracket syntax - Reference-style links `[text][ref]` fail silently if `[ref]: url` is missing—verify all refs exist - Images without alt text: always provide `` even if empty `![]()` for accessibility tools ## Code - Triple backticks inside fenced blocks—use 4+ backticks for outer fence or indent method - Inline backticks containing backtick—wrap with double backticks and pad: ``` `` `code` `` ``` - Language hint after fence affects syntax highlighting—omit only when truly plain text ## Tables - Alignment colons go in separator row: `:---` left, `:---:` center, `---:` right - Pipe `|` in cell content needs backslash escape: `\|` - No blank line before table—some parsers fail - Empty cells need at least one space or break rendering ## Escaping - Characters needing escape in text: `\*`, `\_`, `\[`, `\]`, `\#`, `\>`, `\``, `\\` - Escape not needed inside code spans/blocks - Ampersand only needs escape as `&amp;` when it could form an HTML entity ## Portability - HTML tags work in GitHub but stripped in many renderers—prefer pure Markdown - Extended syntax (footnotes, task lists, emoji shortcodes) not universal—check target parser - YAML frontmatter needs `---` fences and only at file start; some parsers render it as text