x/website: automatic URL fragments for sub-sections of 'Minor changes to the library' are overly repetitive

[bradfitz]

Is something duplicating the fragment names in the release notes?

https://tip.golang.org/doc/go1.24#gotypespkggotypes
https://tip.golang.org/doc/go1.24#encodingjsonpkgencodingjson
https://tip.golang.org/doc/go1.24#archivepkgarchive

I'd expect just archive or pkgarchive at most.

Others are pretty: https://tip.golang.org/doc/go1.24#runtime (which is why I guess the pkg is in there, to distinguish it from https://tip.golang.org/doc/go1.24#runtimepkgruntime ... but that's two runtime in that fragment)

/cc @dmitshur

[dmitshur]

These headings are automatically generated rather than hand-written, and it's likely they got more repetitive after we switched to using Markdown for release notes instead of raw HTML (e.g., issue #64169, CL 539755, CL 342610, etc.). This affects old release notes too, not only Go 1.24 ones.

In the Markdown source, package headings include the import path and a link to docs:

#### [`encoding/json`](/pkg/encoding/json/)

(_content/doc/go1.24.md#L535)

Then goldmark's parser.WithAutoHeadingID() option is used, and it likely ends up concatenating the text and URL when generating the heading ID, leading to the following rendered HTML:

<h4 id="encodingjsonpkgencodingjson"><a href="/pkg/encoding/json/"><code>encoding/json</code></a></h4>

There's definitely room to reduce repetition. Perhaps something like "pkg-{importpath}" would work well for all the 'Minor changes to the library' sub-headings.

[gopherbot]

Change https://go.dev/cl/663335 mentions this issue: _content/doc: remove overly repetitive URL fragments

[seankhliao]

Should this be fixed by manually specifying IDs for all links as in the CL above, or changing the use of WithAutoHeadingID to something custom?

[dmitshur]

I don't think it's viable to rely on manually specifying IDs as in that CL. People will forget to do it in some cases, and changing anchors afterwards on recent release notes might break links.