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 ``` ## 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 #1697. ``` ## 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 ``` ## Frontmatter Frontmatter use in `docs/` varies by document type: **required** for issue specs and EPIC specs, **recommended** for ADRs and refactor plans, and **optional** for short reference pages and README files. Follow the frontmatter convention defined in [`docs/skills/semantic-skill-link-convention.md`](../../../../../docs/skills/semantic-skill-link-convention.md), which specifies the required fields for each document type and the shape of `semantic-links` entries. When a draft issue spec identifies source artifacts it will change, add an `issue-spec: <repo-relative-draft-path>` marker to those artifacts when the link is high-signal. Once the GitHub issue is created, replace the draft-path marker with `issue: #<number>`; do not keep paths that will become stale when the spec moves from `drafts/` to `open/` or `closed/`. ## Repo Markdown vs. GitHub Markdown The `.markdownlint.json` configuration at the repository root applies **only to `.md` files tracked in the repository**. It does not apply to Markdown written on GitHub surfaces such as issue descriptions, PR descriptions, PR review comments, or discussion posts. **Do not wrap lines when writing GitHub issue or PR body text.** Hard-wrapping lines in issue or PR descriptions produces visually broken paragraphs on GitHub's web UI and is harder for human readers to follow. Write each paragraph as a single continuous line and let GitHub's rendering handle the wrapping. | Surface | Governed by `.markdownlint.json` | Line wrapping | | ---------------------- | -------------------------------- | ------------------------------------------------------------ | | `.md` files in repo | Yes | Follow repo config (MD013 disabled, but keep lines readable) | | GitHub issue / PR body | No | Do **not** hard-wrap lines | | GitHub review comments | No | Do **not** hard-wrap lines | ## Filename Conventions New concrete Markdown documents use lowercase filenames. Use **UPPERCASE** only for reusable document templates and the documented conventional exceptions `README.md`, `AGENTS.md`, and folder-style durable-record primary files `ISSUE.md`, `EPIC.md`, `REFACTOR-PLAN.md`, and `PR-REVIEW.md`. Individual document families may define their own lowercase separators, such as kebab-case issue artifacts and timestamped snake_case ADRs. Existing uppercase concrete documents are legacy and may retain their names; do not rename them as unrelated cleanup. A material update or an added issue-local artifact requires migration only for a legacy single-file issue specification. Templates use uppercase names, including `ISSUE.md`, `EPIC.md`, `REFACTOR-PLAN.md`, and `PR-REVIEW-TEMPLATE.md`. Folder-style durable records use the allowed uppercase primary filenames `ISSUE.md`, `EPIC.md`, `REFACTOR-PLAN.md`, and `PR-REVIEW.md`; supporting documents use lowercase, for example `implementation-retrospective.md`. | Category | Convention | Example | | ----------------------- | ---------- | ------------------------------------------------------------------ | | Reusable template | UPPERCASE | `docs/templates/ISSUE.md` | | Concrete durable record | UPPERCASE | `1978-configuration-overhaul-epic/EPIC.md` | | Concrete supporting doc | lowercase | `1978-configuration-overhaul-epic/implementation-retrospective.md` | | Conventional index file | UPPERCASE | `README.md`, `AGENTS.md` | ## 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 an intentional issue/PR reference - [ ] Tables are consistently formatted - [ ] Frontmatter is present and follows `docs/skills/semantic-skill-link-convention.md` - [ ] `linter markdown` and `linter cspell` pass ## Checklist Before Submitting to GitHub Apply this checklist to any Markdown body submitted via the GitHub API or CLI (issues, PR descriptions, review comments, discussion posts) **before** calling the API: - [ ] Each paragraph is written as a single continuous line — do **not** hard-wrap at any fixed column width - [ ] No `#NUMBER` patterns used for enumeration or step numbering - [ ] Any `#NUMBER` present is an intentional issue/PR reference - [ ] Ordered lists use Markdown syntax (`1.` `2.` `3.`) - [ ] Tables are consistently formatted - [ ] No raw HTML unless GitHub's renderer requires it