write-markdown-docs
Guide for writing Markdown documentation in this project. Covers GitHub Flavored Markdown pitfalls, especially the critical
ソース情報
- リポジトリ
- torrust/torrust-tracker-deployer
- ソースの最終更新活動
- 2026年2月25日 19:30
- 検出された SKILL.md の言語
- 英語
- スター
- 5
- フォーク
- 2
インストール方法
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
ソースファイルを確認
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
SKILL.md を表示中
SKILL.md
ソースの指示 · 読み取り専用プレビュー- 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.**
```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)
GitHubで見る