## Problem to solve The old handbook provided linters that checked handbook URLs for correctness in each MR and CI/CD run. 1. Relative URLs 2. 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. 1. Rake task class: `::Lint::HandbookLinkLinter::RelativeLinkChecker` 2. 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 https://gitlab.com/gitlab-com/www-gitlab-com/-/issues/13991 1. Rake task class: `::Lint::HandbookLinkLinter::BareAnchorChecker` 2. 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 1. `markdownlint` calls `markdownlint-cli2` 1. Configuration https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/.markdownlint.yaml?ref_type=heads does not check for relative URLs. 2. `handbooklint` calls `handbook-lint.sh` 1. 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 https://gitlab.com/gitlab-com/content-sites/handbook/-/merge_requests/3870#note_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 1. 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 2. design.gitlab.com uses https://www.npmjs.com/package/linkinator 3. GitLab docs evaluate using lychee https://github.com/lycheeverse/lychee in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/145480 1. https://gitlab.com/gitlab-org/technical-writing-group/markdown-link-check ## Resources 1. Old handbook rake tasks: https://gitlab.com/gitlab-com/www-gitlab-com/-/tree/master/lib/lint/handbook_link_linter?ref_type=heads 2. New handbook 1. markdown-lint.sh https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/scripts/handbook-lint.sh?ref_type=heads 3. markdownlint plugins 1. https://github.com/DavidAnson/markdownlint/issues/586 2. https://github.com/theoludwig/markdownlint-rule-relative-links _Originally noted in https://gitlab.com/gitlab-com/content-sites/handbook/-/issues/151#note_1785529588 now moved into a separate tracking issue._ /cc @marshall007 @cynthia @bmarnane