Skip to content

Fixing tag links in the bilingual documentation

Ticket #178: Fixing clickable tag links in the bilingual documentation
Type: Documentation / Bug Fix / Reliability
Affected Component: mkdocs.yml, docs/tags.md, docs/fr/tags.md, tests/test_docs_config.py, docs/tests/index.md, docs/fr/tests/index.md

1. Context

A behavioral gap had been identified between the English and French versions of the documentation: on the French activity reports, the tags displayed at the top of the page were no longer clickable, while they continued to work correctly in English.

This issue weakened navigation and reduced the usefulness of the tag-based filtering mechanism that had been introduced to make the project history easier to browse.

2. Objective

The goal of this intervention was to restore consistent behavior across both documentation languages and secure the fix with a durable regression safeguard.

Concretely, this work aimed to:

  • restore clickable tag rendering on the French side;
  • stabilize the MkDocs / Material / i18n configuration;
  • add a regression test to prevent the issue from coming back;
  • recalculate and realign the coverage indicator displayed in the test documentation.

3. Delivered fix

3.1 — Repairing the tag rendering mechanism

The legacy [TAGS] placeholder was replaced with the marker supported by Material for MkDocs:

  • ###### activity_report/apr-26_bilingual-tag-links-fix.md:1378-1400/name { #activity_report/apr-26_bilingual-tag-links-fix.md:1378-1400/slug }

This change was applied in:

  • docs/tags.md
  • docs/fr/tags.md

3.2 — Adjusting the documentation configuration

The configuration in mkdocs.yml was simplified to rely on the behavior natively supported by the tags plugin, which restored clickable links in both the English and French generated site.

3.3 — Adding an automated safeguard

The file tests/test_docs_config.py was extended with a regression test that verifies:

  • the mkdocs build completes successfully;
  • English and French tags are rendered as real href links;
  • both tag index pages are generated correctly;
  • the raw placeholder no longer appears in the built site.

3.4 — Updating displayed coverage

The global coverage rate shown in:

  • docs/tests/index.md
  • docs/fr/tests/index.md

was updated to reflect the recalculated value after the new regression test was added.

4. Operational result

The documentation now behaves consistently across both language versions: tags are clickable in French as well as in English, filtering is usable again, and the fix is protected by a dedicated automated regression test.

The verification steps executed during this intervention confirmed:

  • 55 passed, 3 warnings on the pytest suite;
  • a successful mkdocs build --clean;
  • a recalculated global coverage rate of 95%.