Skip to content

Draft: Enable markdownlint link-fragments check for translated docs

What does this MR do?

  1. Adds a new CI job docs-i18n-lint links that validates anchor links in internationalized documentation by:
    • Creating fallback symlinks for missing locale files to the original English docs
    • Running lychee with offline mode and fragment checking on all locale directories
    • Enabling the link-fragments rule in markdownlint configuration
  2. Enables markdownlint's MD051 (link-fragments) rule for /docs-locale to 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

  1. Check what locale directories exist ls -la doc-locale
  2. See what symlinks get created ./scripts/docs_i18n_verify_links.sh
  3. Verify symlinks were created correctly find doc-locale/ -type l | head -10
  4. 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 https://gitlab.com/gitlab-com/localization/docs-site-localization/-/issues/333#note_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-package jobs have a green pipeline running against latest commit.
  • If config/software or config/patches directories are changed, make sure the build-package-on-all-os job within the Trigger:ee-package downstream pipeline succeeded.
  • If you are changing anything SSL related, then the Trigger:package:fips manual job within the Trigger:ee-package downstream pipeline must succeed.
  • If CI configuration is changed, the branch must be pushed to dev.gitlab.org to 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
  • 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.
Edited by Lauren Barker

Merge request reports

Loading