Draft: Enable markdownlint link-fragments check for translated docs
What does this MR do?
- Adds a new CI job
docs-i18n-lint linksthat validates anchor links in internationalized documentation by:- Creating fallback symlinks for missing locale files to the original English docs
- Running
lycheewith offline mode and fragment checking on all locale directories - Enabling the
link-fragmentsrule in markdownlint configuration
- Enables markdownlint's MD051 (link-fragments) rule for
/docs-localeto validate that internal anchor links point to existing headings.
This ensures that internal anchor links work correctly across all documentation locales.
To QA and Test
- Check what locale directories exist
ls -la doc-locale - See what symlinks get created
./scripts/docs_i18n_verify_links.sh - Verify symlinks were created correctly
find doc-locale/ -type l | head -10 - Test lychee directly on a specific locale
lychee --offline --include-fragments doc-locale/ja-jp
Test the markdownlint changes
cd doc-locale && markdownlint-cli2 --config .markdownlint/.markdownlint-cli2.yaml '**/*.mdThis MR turns on markdownlint's link-fragment for /doc-locale
Why are we doing this?
Previously, translated documentation could contain broken anchor links that went undetected. With the recent addition of English anchor links to all translated headings (e.g., ## はじめに {#introduction}), we can now properly validate these links.
This helps ensure:
- All internal anchor links in translated docs are valid
- Users can navigate seamlessly between language versions
- Broken links are caught during CI/CD
Related issues
Related gitlab-com/localization/docs-site-localization#333 (comment 2829368424)
Checklist
See Definition of done.
For anything in this list which will not be completed, please provide a reason in the MR discussion.
Required
-
MR title and description are up to date, accurate, and descriptive. -
MR targeting the appropriate branch. -
Latest Merge Result pipeline is green. -
When ready for review, MR is labeled workflowready for review per the Distribution MR workflow.
For GitLab team members
If you don't have access to this, the reviewer should trigger these jobs for you during the review process.
-
The manual Trigger:ee-packagejobs have a green pipeline running against latest commit. -
If config/softwareorconfig/patchesdirectories are changed, make sure thebuild-package-on-all-osjob within theTrigger:ee-packagedownstream pipeline succeeded. -
If you are changing anything SSL related, then the Trigger:package:fipsmanual job within theTrigger:ee-packagedownstream pipeline must succeed. -
If CI configuration is changed, the branch must be pushed to dev.gitlab.orgto confirm regular branch builds aren't broken.
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 the GitLab Chart opened. gitlab-org/charts/gitlab!4584 (closed) -
Validate potential values for new configuration settings. Formats such as integer 10, duration10s, URIscheme://user:passwd@host:portmay require quotation or other special handling when rendered in a template and written to a configuration file.