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