Skip to content

Docs: verify links in Markdown files - #13

Merged
mlapin merged 1 commit into
masterfrom
docs/link-check
Nov 17, 2026
Merged

mlapin merged 1 commit into
masterfrom
docs/link-check

Conversation

@mlapin

@mlapin mlapin commented Nov 17, 2026

Copy link
Copy Markdown
Owner
  • Coverage: tools/check_docs.py checks every tracked (or new) Markdown file outside vendor/. It reads inline links, images, reference definitions, HTML href/src and bare URLs; links in code are ignored.
  • Local links: the target must be a tracked file with the exact case (macOS forgives case, GitHub does not); heading anchors follow GitHub's slugs, including code spans and links in headings, and Pandoc {#id} attributes.
  • Repository links: github.com/mlapin/libsdca/blob/... at master or the current version tag resolve in the checkout, heading included. blob/main, relative links in docs/PYTHON.md and docs/RUST.md (rendered on PyPI and crates.io) and undefined reference labels fail.
  • External links: --external requests every URL in the Markdown, pyproject.toml, CITATION.cff and rust/Cargo.toml, and checks page anchors. 401/403/429 and a version tag not yet on GitHub are warnings. quality.py keeps the offline check; the release steps in CONTRIBUTING.md add the external run.

Known external failures, outside this PR: https://mlapin.github.io/libsdca/report/ returns 404, and the blob/v0.4.0 links resolve once v0.4.0 is tagged.

Checks: tools/check_docs.py and the documentation tests of tests/python/test_build_config.py.

… external pass

- tools/check_docs.py checks every tracked (or new) Markdown file outside vendor/: inline
  links, images, reference definitions, HTML href/src and bare URLs, with inline code and
  comments masked.
- Targets must match a tracked file with the exact case; headings follow GitHub's slugs
  (code spans and links in headings) and Pandoc {#id} attributes.
- Links to this repository on GitHub at master or the current version tag resolve in the
  checkout; blob/main, relative links in the guides rendered on PyPI and crates.io and
  undefined reference labels fail.
- --external requests every external URL (page anchors included); refusals by hosts and a
  version tag not yet on GitHub are warnings.
- CONTRIBUTING.md and tools/README.md describe the check; the release steps run --external.
@mlapin mlapin changed the title Docs check: every link in every tracked Markdown file Docs: verify links in Markdown files Nov 17, 2026
@mlapin
mlapin merged commit c0c4181 into master Nov 17, 2026
20 checks passed
@mlapin
mlapin deleted the docs/link-check branch November 17, 2026 10:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant