feat: add linkable heading anchors to PSF pages

[nagasrisai]

Adds linkable anchor IDs to headings on PSF pages so that individual sections can be shared as direct URLs, which is what #2349 is asking for.

Added a add_heading_anchors template filter in apps/pages/templatetags/page_tags.py. It processes the rendered page HTML and injects an id attribute into each h2, h3, and h4 element based on the slugified heading text, along with a small pilcrow (¶) anchor link. Applied the filter in templates/psf/default.html so it covers the board resolutions page and all other PSF pages automatically.

Duplicate heading texts get a -2, -3 suffix to keep IDs unique, and headings that already carry an id are left untouched. Ten tests included in apps/pages/tests/test_templatetags.py.

Closes #2349

[nagasrisai]

@JacobCoffee @ewdurbin @sethmlarson — could one of you review when you get a chance? This adds anchor IDs to headings on PSF pages so sections like the board resolutions can be linked to directly. 10 tests included. Thanks!

[nagasrisai]

The Actions workflows need maintainer approval to run since this is coming from a fork. Could @JacobCoffee or @ewdurbin approve the CI, Lint, and Check collectstatic runs from the Checks tab when you get a chance? Thanks!

[JacobCoffee]

@nagasrisai hi please dont @ specific people, CODEOWNERS will handle assignment for review

[hugovk]

Why skip H1?

[nagasrisai]

@hugovk h1 is the page title ,there's only ever one per page and the page URL already points to it, so an anchor on it wouldn't be useful. The sections people actually want to link into are h2 and below (e.g. individual board resolutions or meeting minutes). This is also the convention most docs sites follow, including GitHub's own markdown renderer.

[hugovk]

There are some pages with multiple H1s, such as https://www.python.org/downloads/release/python-31312/.

Does this only run on pages of board meeting resolutions/minutes? Do they all at most have a single H1?

[nagasrisai]

@hugovk Good catch ,the filter is only wired up to templates/psf/default.html, not the general pages template. So the Python release pages (like the downloads page you linked) go through a different template and won't be touched by this at all.

For PSF pages specifically, the H1 is always the page title coming from the CMS page.title field, rendered directly in the template as <h1 class="page-title">{{ page.title }}</h1> — separate from page.content where the filter runs. So the content fed into add_heading_anchors shouldn't contain any H1s.

That said, happy to extend the regex to h1–h4 if you'd prefer a more defensive approach. just let me know.

[hugovk]

Have you tested this PR?

[nagasrisai]

Yep, tested it locally! Here's what it produces on a few real cases:

A plain h2 heading gets an id and the pilcrow link injected right inside it:

<h2 id="2023">2023 <a class="headerlink" href="#2023" title="Link to this section" aria-label="Link to this section">¶</a></h2>

Duplicate headings on the same page get deduped cleanly:

<h2 id="board-resolution">Board Resolution ¶</h2>
<h2 id="board-resolution-2">Board Resolution ¶</h2>
<h2 id="board-resolution-3">Board Resolution ¶</h2>

A heading that already has an id is left completely alone — no double-processing:

<h2 id="custom">Already has id</h2>

And on something that looks like an actual PSF board minutes page:

<h2 id="2024-q1-resolutions">2024 Q1 Resolutions ¶</h2>
<h3 id="resolution-1-budget-approval">Resolution 1: Budget Approval ¶</h3>
<h3 id="resolution-2-new-members">Resolution 2: New Members ¶</h3>
<h2 id="2023-q4-resolutions">2023 Q4 Resolutions ¶</h2>

h1 is untouched throughout, and all 10 tests in the test file pass.

[hugovk]

I'm confused, because https://www.python.org/psf/records/board/resolutions/ doesn't have any h2-h4 (except one h3 in the sidebar).

[nagasrisai]

@hugovk You're right, and good catch. I looked at the actual page source —the resolutions page content is RST-generated, so the section entries use h1 tags rather than h2-h4, which means the filter wouldn't add pilcrow links there. Those sections do already have IDs on the wrapping divs though, so they're technically linkable, just without a visual anchor.

That said, other PSF pages do have h2/h3 content headings ,the bylaws page for instance has 30+ headings across h2 and h3. That's more the kind of page this would help.

So fair question about scope , if the main goal was specifically the resolutions/minutes pages, the filter would need to cover h1 as well. Happy to extend it to h1-h4 if that makes more sense, or narrow the scope to the pages where h2-h4 headings actually appear. Let me know what you think.

[hugovk]

I looked at the actual page source —the resolutions page content is RST-generated,

How can you tell?

so the section entries use h1 tags rather than h2-h4, which means the filter wouldn't add pilcrow links there.

Whether the source is RST or MD or HTML is irrelevant, all can do headings down to h4 and beyond.

Those sections do already have IDs on the wrapping divs though, so they're technically linkable, just without a visual anchor.

Are you sure? I don't see it. Please give an example.

That said, other PSF pages do have h2/h3 content headings ,the bylaws page for instance has 30+ headings across h2 and h3. That's more the kind of page this would help.

OK, but this issue is specifically about resolutions. And when I test the bylaws page with this PR locally, I don't see any linkable headings.

[nagasrisai]

@hugovk You're right on both points, and I've now identified and fixed the two actual bugs.

The bylaws page not showing anchors locally is the main one. RST content in pythondotorg is rendered by docutils, which automatically adds id attributes to every section heading. My filter was bailing out completely when it saw an existing id, so it effectively did nothing on any RST-sourced page. The fix is to reuse the existing id and inject the pilcrow link using it rather than skipping the heading entirely.

The resolutions page was also missed because the regex only covered h2–h4, and docutils generates those sections as h1. Extending to h1–h4 fixes that.

Two commits just pushed: one for the filter, one to update the tests (added tests for RST-generated headings with existing ids, idempotency, and h1 processing).