write-markdown-docs

# Writing Markdown Documentation ## Critical: #NUMBER Auto-links to GitHub Issues **GitHub automatically converts `#NUMBER` → link to issue/PR/discussion.** ```markdown ❌ Bad: accidentally links to issues - Task #1: Set up infrastructure ← links to GitHub issue #1 - Task #2: Configure database ← links to GitHub issue #2 Step #1: Install dependencies ← links to GitHub issue #1 ``` **The links pollute the referenced issues with unrelated backlinks and confuse readers.** ### Fix: Use Ordered Lists or Plain Numbers ```markdown ✅ Solution 1: Ordered list (automatic numbering) 1. Set up infrastructure 2. Configure database 3. Deploy application ✅ Solution 2: Plain numbers (no hash) - Task 1: Set up infrastructure - Task 2: Configure database ✅ Solution 3: Alternative formats - Task (1): Set up infrastructure - Task [1]: Set up infrastructure - Task No. 1: Set up infrastructure ``` ## When #NUMBER IS Intentional Use `#NUMBER` only when you explicitly want to link to that GitHub issue/PR: ```markdown ✅ Intentional: referencing issue This implements the behavior described in #42. Closes #374. Parent: #274 (Epic: Adopt Agent Skills) ``` ## Other GFM Auto-links to Know ```markdown @username → links to GitHub user profile (use intentionally for mentions) abc1234 (SHA) → links to commit (useful for references) owner/repo#42 → cross-repo issue link ``` ## Checklist Before Committing Docs - [ ] No `#NUMBER` patterns used for enumeration or step numbering - [ ] Ordered lists use Markdown syntax `1.` `2.` `3.` - [ ] Any `#NUMBER` present is intentional issue/PR reference - [ ] Table formatting is consistent (use a Markdown linter) ## Reference Full guide: [`docs/contributing/github-markdown-pitfalls.md`](../../docs/contributing/github-markdown-pitfalls.md)