# Markdown

> Generate clean, portable Markdown that renders correctly across parsers.

- Skill: `modbender/markdown` (Agent Skill)
- Install (CLI): `npx skillmds@latest add modbender/markdown`
- Raw SKILL.md: https://api.skillmd.com/api/skills/modbender/markdown/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: modbender (https://skillmd.com/u/modbender)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/modbender/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 `&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