x/pkgsite: display table of contents (TOC) in command documentation

[dmitshur]

What is the URL of the page with the issue?

https://pkg.go.dev/cmd/go

Screenshot

What did you do?

Visited command documentation. As an example, see https://pkg.go.dev/cmd/go, but this applies to any command (package with name "main").

What did you expect to see?

A table of contents, like on https://golang.org/cmd/go:

What did you see instead?

No table of contents.

This is a feature request to have feature parity with previous documentation rendering on golang.org and the godoc package documentation viewer.

/cc @julieqiu

[myitcv]

A table of contents, like on https://golang.org/cmd/go:

Did you perhaps intend for the comparison here to be with https://godoc.org/cmd/go?

[dmitshur]

I meant to compare with golang.org (powered by x/tools/godoc). godoc.org (powered by github.com/golang/gddo) doesn't implement this feature.

Some implementation notes.

golang.org renders (via x/tools/godoc package) the table of contents on the frontend via a generateTOC function here:

• https://github.com/golang/tools/blob/a49f79bcc2246daebe8647db377475ffc1523d7b/godoc/static/godocs.js#L369

pkg.go.dev does not need to do this on the frontend, it can render a table of contents on the backend (together with the where all of package documentation rendering currently happens).

This table of contents is applicable only for commands; library packages already have an index (the one that lists all the functions, types, methods, etc.) which serves as a table of contents.

x/tools/godoc uses a div named "manual-nav" to disable the frontend from generating a table of contents for non-commands. See:

• https://github.com/golang/tools/blob/a49f79bcc2246daebe8647db377475ffc1523d7b/godoc/static/godocs.js#L33-L35
• https://github.com/golang/tools/blob/a49f79bcc2246daebe8647db377475ffc1523d7b/godoc/static/package.html#L57-L58

[gopherbot]

Change https://golang.org/cl/288552 mentions this issue: internal/experiment: create command-toc experiment

[gopherbot]

Change https://golang.org/cl/288553 mentions this issue: content,internal/godoc: add table of contents to command pages

[jamalc]

Here is a mockup of the TOC feature.

[hyangah]

Index and "Jump to" feature for command documentation would be nice too.

[jamalc]

@hyangah that's a good idea, would you file that under a new issue? We'll need some discussion and UX review to figure out how it would work.