Re-add relative URL and anchor linter for Markdown (CLI, CI/CD)
Problem to solve
The old handbook provided linters that checked handbook URLs for correctness in each MR and CI/CD run.
- Relative URLs
- URL anchors - with some exceptions.
bundle exec rake lint
in https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/.gitlab-ci.yml?ref_type=heads#L704 and https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/lib/tasks/lint.rake?ref_type=heads The link linter is in https://gitlab.com/gitlab-com/www-gitlab-com/-/tree/master/lib/lint?ref_type=heads
Relative URLs
The old handbook was building a tree of relative URLs, and checked all pages against it. That prevented broken URLs to being merged.
- Rake task class:
::Lint::HandbookLinkLinter::RelativeLinkChecker
- Exception paths are documented in the
TEMPORARY_IGNORE
variable in https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/lib/lint/handbook_link_linter/relative_link_checker.rb?ref_type=heads
URL anchors
The old handbook provided a rake linting task to check for URL anchors. It had an exceptions list of prefixes to exclude.
For the marketing handbook restructuring in FY23, I went into fixing most of the broken URL anchors in gitlab-com/www-gitlab-com#13991 (closed)
- Rake task class:
::Lint::HandbookLinkLinter::BareAnchorChecker
- The exception paths are documented in the
TEMPORARY_IGNORED_ANCHORS
variable in https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/lib/lint/handbook_link_linter/bare_anchor_checker.rb?ref_type=heads
New handbook linters
Currently, no URL checks exist in CI/CD. https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/.gitlab-ci.yml?ref_type=heads#L155
-
markdownlint
callsmarkdownlint-cli2
- Configuration https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/.markdownlint.yaml?ref_type=heads does not check for relative URLs.
-
handbooklint
callshandbook-lint.sh
- The script https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/scripts/handbook-lint.sh?ref_type=heads only checks for CODEOWNERS, not links.
Proposal
Re-implement the handbook URL linters as CLI command, integrated into CI/CD for
-
Relative URL linting, e.g. that /solutions
is marked an error on handbook.gitlab.com because it exists on about.gitlab.com (see !3870 (comment 1785825751)) -
Markdown anchor linting, e.g. that # problem to solve
on/tools-and-tips
becomes/tools-and-tips/#problem-to-solve
in all handbook pages.
Ideas
- Maybe there is a possibility as a Hugo module or markdownlint plugin which provides this functionality out of the box. A quick search led to https://github.com/DavidAnson/markdownlint/issues/586 and https://github.com/theoludwig/markdownlint-rule-relative-links
- design.gitlab.com uses https://www.npmjs.com/package/linkinator
- GitLab docs evaluate using lychee https://github.com/lycheeverse/lychee in gitlab-org/gitlab!145480 (merged)
Resources
- Old handbook rake tasks: https://gitlab.com/gitlab-com/www-gitlab-com/-/tree/master/lib/lint/handbook_link_linter?ref_type=heads
- New handbook
- markdownlint plugins
Originally noted in #151 (comment 1785529588) now moved into a separate tracking issue.