Write Markdown Docs

Documents

write-markdown-docs

Write Markdown Docs is an Agent Skill for documents published in the torrust/torrust-tracker repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Guide for writing Markdown documentation in this project. Covers GitHub Flavored Markdown pitfalls, especially the critical

View on GitHub ↗

QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

Open your project in Codex.
Copy and paste the prompt below.
Review files and risks before approving any action.

Prompt to paste

Inspect the Agent Skill at https://github.com/torrust/torrust-tracker/blob/HEAD/.github/skills/dev/planning/write-markdown-docs/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/write-markdown-docs, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

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 #1697.

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

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, which specifies the required fields for each document type and the shape of semantic-links entries.

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

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