Add docs-i18n-lint links CI job for anchor link validation
What does this MR do?
- 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
-
- Updates existing new
docs-i18n-lint paths
CI jobs:- To use
docs_i18n_verify.sh --verify-paths
- To use
- 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
- Enables markdownlint's MD051 (link-fragments) rule for
/doc-locale
to validate that internal anchor links point to existing headings.
To QA and Test
- Check what locale directories exist
ls -la doc-locale
- Test path verification: ./scripts/docs_i18n_verify.sh --verify-paths
- Test link checking:
./scripts/docs_i18n_verify.sh --check-links
- See what symlinks get created by comment out the trap cleanup line:
ls -la lychee_test_$timestamp
- 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
, duration10s
, URIscheme://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