# Fix Sphinx Linkcheck

> Fix Sphinx Linkcheck is an Agent Skill for testing & quality published in the canonical/mir repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Fix Sphinx linkcheck failures in Mir docs: disambiguate ambiguous internal links, replace stale external anchors, add known 403-only URLs to linkcheck_ignore, and verify with doc-clean-doc, doc-html, doc-linkcheck targets.

- Skill name: `fix-sphinx-linkcheck`
- Category: [Testing & Quality](https://www.openparable.com/skill/testing-quality/1)
- Source: https://github.com/canonical/mir/blob/HEAD/.github/skills/fix-sphinx-linkcheck/SKILL.md
- Repository: canonical/mir (775 GitHub stars when collected)

## SKILL.md

# Fix Sphinx Linkcheck

Use this workflow when CI reports Sphinx linkcheck failures in the Mir docs.

Reference for destination resolution and disambiguation:
https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#default-destination-resolution

## Steps

1. Identify failing links from `doc-linkcheck` output.
1. For ambiguous internal references (for example multiple matches for one label), disambiguate with Sphinx's standard-domain label role.
   - Preferred: `` {ref}`my-label`  ``.
   - Example: use `` {ref}`release-notes`  `` instead of doc/path-style links.
1. For missing anchors, replace with a currently working URL/anchor from upstream docs.
1. For stable, known 403 responses from external sites, add a focused regex to `doc/sphinx/conf.py` `linkcheck_ignore`.
1. Verify in sequence:

```bash
cmake -B ~/build .
cmake --build ~/build --target doc-clean-doc
cmake --build ~/build --target doc-html
cmake --build ~/build --target doc-linkcheck
```

## Rules

- Keep edits minimal and local to the reported failures.
- Prefer `` {ref}`label`  `` links for internal docs.
- Prefer explicit targets created with `(my-label)=` over implicit heading anchors.
- Keep ignore regexes narrowly scoped to avoid masking real failures.

---

Source: https://www.openparable.com/skill/testing-quality/fix-sphinx-linkcheck (OpenParable). Cite the canonical URL above.
