x/pkgsite/cmd/pkgsite: create table of contents from headings in package overview

[jimmyfrasche]

Packages with large overviews often have multiple headings.

Creating a table of contents from those headings allows the initial reader to gauge the scope of the package at a glance and allows the return reader to skip easily to the desired section.

Screenshot

Originally discussed in #18342 The majority of the discussion starting at #18342 (comment)

Prototype CL https://golang.org/cl/69030

Per golang.org/s/owners, cc: @andybons @agnivade @bradfitz @griesemer @ysmolsky

cc @dsnet for any interference this may cause with #25444

[agnivade]

I am neutral to this. But if we are to do this, I agree with @neild's comment that this should be merged with the top level table of contents. Having a separate table of contents inside the Overview section feels a bit inconsistent.

[jimmyfrasche]

I don't feel strongly either way on that point: I just did the easiest thing that worked.

But if we're talking consistency the package index is a separate table of contents as is the list of examples (though that's sorta part of the package index?). The ToC at the top is like a super-ToC to the more specific ToCs so adding it to the super-ToC seems less consistent to me.

[agnivade]

Fair enough. Although the links from inside "Index" can be considered as ToC to the rest of the page, whereas if you add the new ToC inside "Overview", it just jumps to headings inside that section.

What do you think about this ?

Overview
    Sub-heading1
    Sub-heading2
Index
    Examples
    Package files

The top level links "Overview" and "Examples", both link to collapsibles. And links under them go inside that collapsible. This also fixes the inconsistency that "Examples" is linkable, but "Package files" is not.

[jimmyfrasche]

I like that.

[rsc]

The suggestion two comments up (one big ToC, not scattered ToC pieces) looks great. @jimmyfrasche, can you update your CL to do that?

[dsnet]

If we're going with the ToC approach, can we please consider how that would work if we ever do #18342?

Edit: I'm not opposed to this, just wanted to sure we think about it.

[gopherbot]

Change https://golang.org/cl/69030 mentions this issue: x/tools/cmd/godoc: add table of contents for Overview section

[jimmyfrasche]

@rsc I've updated the CL. Not sure who to add for reviewers but all are welcome.