write-markdown-docs

name	write-markdown-docs
description	Guide for writing Markdown documentation in this project. Covers GitHub Flavored Markdown pitfalls, especially the critical
metadata	{"author":"torrust","version":"1.0"}

Writing Markdown Documentation

Critical: #NUMBER Auto-links to GitHub Issues

GitHub automatically converts #NUMBER → link to issue/PR/discussion.

❌ 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

✅ 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:

✅ Intentional: referencing issue
This implements the behavior described in #42.
Closes #374.
Parent: #274 (Epic: Adopt Agent Skills)

Other GFM Auto-links to Know

@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