ci(pull-request): add Sphinx linkcheck to catch dead external links

.github/workflows/pull-request.yml

@@ -39,6 +39,13 @@ jobs:
             - name: Build Documentation
               run: ./build.sh
 
+            # Reuse the rst/ tree that build.sh already generated (collections
+            # rendered + normalized) and validate every external link. Internal
+            # :ref:/:doc: references are already enforced by the nitpicky html
+            # build above; this catches dead external URLs.
+            - name: Check Links
+              run: sphinx-build -b linkcheck rst build/linkcheck -c .
+
     security-secrets:
         name: Secret Detection Scan
         uses: arillso/.github/.github/workflows/security-secrets.yml@2026-06-14

conf.py

@@ -65,6 +65,26 @@
 
 nitpicky = True
 
+# Link checking (sphinx-build -b linkcheck). Internal :ref:/:doc: references are
+# validated by the regular html build (nitpicky); these options harden the
+# external HTTP checks against flaky endpoints so CI fails only on genuinely
+# broken links.
+linkcheck_retries = 2
+linkcheck_timeout = 15
+linkcheck_workers = 5
+# Treat anchor-only failures as warnings, not errors: many sites render anchors
+# client-side, so a missing #fragment is not a broken page.
+linkcheck_anchors = False
+# Hosts that rate-limit or block automated HEAD/GET requests but are known-good.
+linkcheck_ignore = [
+    # galaxy.ansible.com / hub.docker.com return 403 to non-browser clients.
+    r"https://galaxy\.ansible\.com/.*",
+    r"https://hub\.docker\.com/.*",
+    # Non-HTTP URI schemes that appear in generated collection RST (e.g. the
+    # tailscale_role "tag:" ACL tags) and that linkcheck cannot resolve.
+    r"^tag:.*",
+]
+
 # Sitemap configuration
 html_baseurl = "https://guide.arillso.io/"
 sitemap_url_scheme = "{link}"

rst/guide/best-practices/standards.rst

@@ -568,4 +568,4 @@ Files to Avoid
    * :ref:`contributing` - How to contribute (code style, testing, development)
    * :ref:`cicd` - CI/CD workflows and linter configurations
    * :ref:`compatibility` - Version requirements and platform support
-   * `STANDARDS.md on GitHub <https://github.com/arillso/.github/blob/main/STANDARDS.md>`_
+   * `arillso/.github on GitHub <https://github.com/arillso/.github>`_ - shared org standards and reusable workflows

rst/guide/reference/compatibility.rst

@@ -665,9 +665,12 @@ Current Known Issues
 Version-Specific Issues
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Issues are tracked per version in GitHub Issues.
-
-See: https://github.com/arillso/ansible.*/issues
+Issues are tracked per version in GitHub Issues, in each collection's
+repository (for example `arillso/ansible.system
+<https://github.com/arillso/ansible.system/issues>`_,
+`arillso/ansible.agent <https://github.com/arillso/ansible.agent/issues>`_,
+and `arillso/ansible.container
+<https://github.com/arillso/ansible.container/issues>`_).
 
 Compatibility Checklist
 -----------------------
@@ -742,7 +745,9 @@ Release Schedule
 **Subscribe to releases:**
 
 * GitHub: Watch → Custom → Releases
-* RSS: https://github.com/arillso/ansible.*/releases.atom
+* RSS: each collection exposes a release feed at
+  ``https://github.com/arillso/<repository>/releases.atom`` (for example
+  `ansible.system <https://github.com/arillso/ansible.system/releases.atom>`_)
 
 Next Steps
 ----------