docs: cross-link sweep - every .md reachable, referenced, and linking its neighbors #245

New issue

Closed

opened 2026-07-17 19:49:15 +00:00 by hexajon · 0 comments

hexajon commented

2026-07-17 19:49:15 +00:00

(Migrated from codeberg.org)

Scope:

Inventory every .md in the repo (README, docs/ tree, docs/adr, docs/reference, docs/guides, docs/contributing, docs/safety, docs/architecture, skills/*/SKILL.md, conformance notes). For each, answer: is it reachable from the documentation roots (README and docs/README) by following links? Does it link back to its parent index? Do the docs it mentions by name carry an actual link?
Fix the gaps: orphaned files get linked from the right index (or deliberately retired if truly dead); prose that names another doc gains the link; parent indexes list every child. Generated reference pages follow their generator (fix internal/docs sources, not the output).
Bare URLs and name-drops of docs that exist ("see the releasing runbook") become proper relative links.
Deliverable includes the audit: a short table in the PR body - every .md, reachable yes/no before, action taken.

Acceptance criteria:

check-doc-links.sh still green (no new broken links introduced).
Zero orphans: every non-generated .md is reachable from a documentation root, or its removal is justified in the PR body.
Every docs/ subdirectory index lists all its children.
If a cheap structural guard falls out naturally (e.g. extending check-doc-links.sh with an orphan check so the property holds permanently), include it; if it needs real design, file the follow-up instead of gold-plating.

A repo-wide sweep of every .md file for cross-linking health. scripts/check-doc-links.sh already proves that existing links resolve; this sweep covers what it cannot: links that are missing rather than broken. Scope: - Inventory every .md in the repo (README, docs/ tree, docs/adr, docs/reference, docs/guides, docs/contributing, docs/safety, docs/architecture, skills/*/SKILL.md, conformance notes). For each, answer: is it reachable from the documentation roots (README and docs/README) by following links? Does it link back to its parent index? Do the docs it mentions by name carry an actual link? - Fix the gaps: orphaned files get linked from the right index (or deliberately retired if truly dead); prose that names another doc gains the link; parent indexes list every child. Generated reference pages follow their generator (fix internal/docs sources, not the output). - Bare URLs and name-drops of docs that exist ("see the releasing runbook") become proper relative links. - Deliverable includes the audit: a short table in the PR body - every .md, reachable yes/no before, action taken. Acceptance criteria: - check-doc-links.sh still green (no new broken links introduced). - Zero orphans: every non-generated .md is reachable from a documentation root, or its removal is justified in the PR body. - Every docs/ subdirectory index lists all its children. - If a cheap structural guard falls out naturally (e.g. extending check-doc-links.sh with an orphan check so the property holds permanently), include it; if it needs real design, file the follow-up instead of gold-plating.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

sixfold-space/madtea#245

No description provided.

Rows
Columns