Resolve "Duplicate headings in shortcodes can interfere with the TOC"

Mateo Penagosrequested to merge
555-duplicate-headings-in-shortcodes-can-interfere-with-the-toc into main

What does this MR do and why?

Headings authored inside the tabs shortcode are excluded from the table of contents (TOC).

Each tab was rendering it's own headers in the TOC and would not be correctly nested,

The result is a confusing TOC:

  • Headings from tabs appear in the TOC in document order and out of sync with what the reader actually sees. A heading that lives in a non-selected tab still shows up in the TOC, so the TOC order no longer matches the visible page.
  • Clicking such an entry does nothing useful since it can't scroll to a heading that's hidden in an unselected tab.
  • When two headings across tabs share a name, they produce duplicate DOM IDs.

This MR adds these headers to the TOC ignoreList

Related

Screenshots, screen recordings, or links to review app

Link Screenshot
production image.png
Review app image.png

Test page: Online garbage collection monitoring → Monitor task queues → Check the health of online garbage collection on container_registry_metadata_database. Before: the "GitLab 18.9 and earlier" tab's headings ("Connect to the GitLab container registry metadata database", etc.) appear in the TOC out of order.

How to set up and validate locally

  1. Configure a local GitLab Docs environment.
  2. Check out this branch.
  3. Run make view and open http://localhost:1313/administration/packages/container_registry_metadata_database/.
  4. Scroll to Check the health of online garbage collection and confirm the headings inside the tabbed block no longer appear in the right-hand TOC, while all page-level headings still do.
  5. Spot-check a code-only tab page (e.g. /integration/saml/) to confirm its TOC is unchanged.

Merge request acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

  •  I have evaluated the MR acceptance checklist for this merge request.
    •  If this MR changes how markdown is interpreted, share this MR in the #tech-docs-localization slack channel.
Edited by Mateo Penagos

Merge request reports