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 ![alt](url) 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 & 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