feat: add linkable heading anchors to PSF pages by nagasrisai · Pull Request #2966

feat: add linkable heading anchors to PSF pages by nagasrisai · Pull Request #2966 · python/pythondotorg

added 4 commits

March 18, 2026 17:45

Adds a custom template filter that post-processes rendered page HTML
to inject id attributes and pilcrow self-link anchors into h2-h4
headings. Duplicate slugs get a -N suffix to prevent id collisions.
Headings that already carry an id are left untouched.

Part of python#2349

Loads the new page_tags library and pipes page content through the
add_heading_anchors filter so that every h2-h4 in a PSF page (including
the board resolutions listing) gets a stable id attribute and a
pilcrow anchor link for direct linking.

Part of python#2349

10 test cases covering: h2/h3/h4 processing, h1/h5 exclusion,
duplicate-slug deduplication, existing-id passthrough, nested HTML
stripping, non-heading passthrough, empty string, empty text, and
anchor placement inside the heading element.

Two bugs fixed:

1. The regex only matched h2-h4, so RST-generated pages like the board
   resolutions page (which use h1 section headings) received no anchors.
   Extended to h1-h4.

2. Headings that already carry an id attribute (docutils/RST injects
   these automatically on every section heading) were silently skipped.
   The filter now reuses the existing id and injects the pilcrow link
   using it, which is exactly what is needed for RST-sourced pages like
   the bylaws and resolutions pages.

Also added idempotency guard so running the filter twice is safe.

Reflects two changes to the filter:
- h1 headings are now processed (not just h2-h4)
- headings with existing ids now get pilcrow links injected

New tests added: RST-generated headings, idempotency guard, h1 processing.