Skip to content

ci: check relative Markdown links and anchors #563

Closed

Description

Summary

Nothing in CI checks the repository's relative Markdown links. #529 moved the design documentation, numbered its sections, and retargeted every inbound link by hand, verified with a one-off script. That script also found an older broken link: line 942 of aci_edge_sandboxes/README.md links #native-proxy-and-forwarded-ports, but #512 renamed that heading to "Native proxy and host loopback".

Why

  • Section anchors now carry numbers. Documents link into the architecture guide through anchors such as 3.2-clock-and-time.md#3210-guest-obligations and 5.1-boot-protocol.md#511-linux-direct-loader, from doc/benchmarks.md, doc/build.md, doc/ci.md, doc/run.md, doc/usage.md, and doc/guests/. Renumbering or renaming a section breaks them silently: GitHub opens the page at its top.
  • Code cites documents by path. After doc: replace doc/design with an architecture-only design guide #529 removed doc/design/time-abi.md, the comments that cited it had to be found by search; time ABI: retarget citations of the removed specification and rehome its reference detail #562 tracks the citations that remain. A check of the doc/ paths in tracked files would have listed them.
  • The quality job covers documentation-only changes. Lint, typing, and formatting runs for every non-draft pull request, including documentation-only ones, which skip the workloads, so a check in check-quality runs on the changes most likely to break a link.

Tasks

  • Fix the anchor on line 942 of aci_edge_sandboxes/README.md.
  • Add a step to .github/actions/check-quality/action.yml that resolves every relative link and image target in the tracked Markdown files outside openvmm/, and every anchor against GitHub's heading slugs, ignoring fenced and inline code. A small script under scripts/ stays under ruff and pyright and needs no new dependency.
  • Optionally, also check the doc/ paths that tracked files mention, with an allowlist for test fixtures such as doc/notes.md in scripts/test_nvx_tools.py.

Activity

  1. added 20 commits that reference this issue on Oct 15, 2026
    2407da7
    399a1b7
    447cdcc
    a346d21
    0d3fb04
    6c90ad2
    d064875
    7db22c1
    b5af641
    80ccfbd
    e1b664b
    eb1cd36
    c1cd88a
    528b02e
    9612b9a
    9f0d7eb
    4c2d855
    46839ab
    d76968d
    0c3db01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

documentationImprovements or additions to documentation

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions