x/pkgsite: possible change in how example links work

[ianlancetaylor]

https://golang.org/cl/353391 points out that a link in Effective Go () does not work. The link is https://golang.org/pkg/strings/#example_Map. That link currently just goes to the docs for the strings package. If we change the underscore to a hyphen (https://golang.org/pkg/strings/#example-Map) then it links to the example.

The link has been there since 2013 (added in https://golang.org/cl/7454044) and it seems to me unlkely that nobody ever checked that the link worked. While I can't prove it, it seems much more likely that this broke when golang.org was moved over to pkg.go.dev.

It seems to me that we should make the underscore links work for examples, unless there is some good reason not to. Thanks.

[dmitshur]

The old golang.org/pkg/ documentation server indeed used anchors for examples that don't exactly match those on pkg.go.dev. When pkg.go.dev was in its early development stages in 2019, since it was a new and different website, it was used as an opportunity to adjust the scheme for example anchors be slightly cleaner looking. For example, a package-scoped example named TextMarshalJSON used to be #example__textMarshalJSON, but it became #example-package-TextMarshalJSON on pkg.go.dev.

Unfortunately, when golang.org/pkg/ started to redirect to pkg.go.dev, any old links to golang.org/pkg/ that happen to include example anchors would no longer highlight the target example. Not unless the old anchors are converted or otherwise handled.

[rsc]

It's certainly possible to put in dummy <span id="foo"></span> tags to keep old links working. I think we should try to do that, if it's not too hard. The code generating the old ids must be easy to grab.