Skip to content

Add docs-i18n-lint links CI job for anchor link validation

What does this MR do?

  1. Adds a consolidated docs_i18n_verify.sh script that provides two verification modes:
    • --verify-paths: Checks that all localized documentation files have corresponding English originals
    • --check-links: Creates a temporary directory with fallback symlinks and validates anchor links using lychee
  2. Updates existing new docs-i18n-lint paths CI jobs:
    • To use docs_i18n_verify.sh --verify-paths
  3. Adds a new docs-i18n-lint links CI job to validate anchor links in internationalized documentation by:
    • Creating a temporary test directory (/lychee_test_$timestamp) at the project root
    • Generating fallback symlinks for missing locale files to the original English docs
    • Running lychee with offline mode and fragment checking
    • Automatically cleaning up the temporary directory after testing
  4. Enables markdownlint's MD051 (link-fragments) rule for /doc-locale to validate that internal anchor links point to existing headings.

To QA and Test

  1. Check what locale directories exist ls -la doc-locale
  2. Test path verification: ./scripts/docs_i18n_verify.sh --verify-paths
  3. Test link checking: ./scripts/docs_i18n_verify.sh --check-links
  4. See what symlinks get created by comment out the trap cleanup line: ls -la lychee_test_$timestamp
  5. Add a bad internal link to a translated file, and run ./scripts/docs_i18n_verify.sh --check-links to see lychee fail

Test the markdownlint changes

cd doc-locale && markdownlint-cli2 --config .markdownlint/.markdownlint-cli2.yaml '**/*.md

Example Pipelines

What Pipeline Notes
Added a bad link to /doc-locale docs-i18n-lint links & docs-i18n-lint markdown i18n linting jobs successfully identified the bad link
Added bad link to /doc, to ensure existing lychee on English works docs-lint links & docs-lint markdown Existing linting jobs successfully identified the bad link

Checklist

See Definition of done.

For anything in this list which will not be completed, please provide a reason in the MR discussion.

Required

  • Merge Request Title and Description are up to date, accurate, and descriptive
  • MR targeting the appropriate branch
  • MR has a green pipeline on GitLab.com
  • When ready for review, MR is labeled "~workflow::ready for review" per the Distribution MR workflow

Expected (please provide an explanation if not completing)

  • Test plan indicating conditions for success has been posted and passes
  • Documentation created/updated
  • Tests added
  • Integration tests added to GitLab QA
  • Equivalent MR/issue for omnibus-gitlab opened gitlab-org/omnibus-gitlab!8802
  • Validate potential values for new configuration settings. Formats such as integer 10, duration 10s, URI scheme://user:passwd@host:port may require quotation or other special handling when rendered in a template and written to a configuration file.

Related issues

Related https://gitlab.com/gitlab-com/localization/docs-site-localization/-/issues/333

Edited by Lauren Barker

Merge request reports

Loading