Skip to content

go.dev: include '¶' permalinks in all package doc subheadings #36808

New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

#

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Jump to bottom
Closed
myitcv opened this issue Jan 27, 2020 · 5 comments
Closed

go.dev: include '¶' permalinks in all package doc subheadings #36808

myitcv opened this issue Jan 27, 2020 · 5 comments
Labels
FeatureRequest Issues asking for a new feature that does not need a proposal. FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done. pkgsite/dochtml Issues related to package documentation in pkgsite pkgsite
Milestone
pkgsite/dochtml

Comments

@myitcv
Copy link
Member

myitcv commented Jan 27, 2020

What is the URL of the page with the issue?

https://pkg.go.dev/testing?tab=doc

What is your user agent?

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.66 Safari/537.36

Screenshot

Screen Shot 2020-01-27 at 19 12 01

What did you do?

Tried to link to the "Benchmarks" subsection of the testing package docs.

What did you expect to see?

Each subheading to be a link such that hovering over it (the heading) a symbol should appear, like on godoc:

Screen Shot 2020-01-27 at 19 12 17

Clicking that link should then change to the address bar URL to include the fragment. For example on godoc, for the "Benchmarks" subsection we end up with the URL:

https://godoc.org/testing#hdr-Benchmarks

What did you see instead?

No ability to link to subsections of package documentation.
@myitcv myitcv added NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite labels Jan 27, 2020
@julieqiu
Copy link
Member

Would you mind clarifying if you are able to link subsections today using the same URL scheme from godoc.org? For example:

https://pkg.go.dev/testing?tab=doc#hdr-Benchmarks

takes me to:
image

My understanding is that this issue is specifically asking to add a clickable symbol next to each subheading.

/cc @dmitshur

@julieqiu julieqiu added the FeatureRequest Issues asking for a new feature that does not need a proposal. label Jan 29, 2020
@myitcv
Copy link
Member Author

myitcv commented Jan 30, 2020

@julieqiu

Would you mind clarifying if you are able to link subsections today using the same URL scheme from godoc.org?

As you demonstrated, that appears to work (not that I had tried)

My understanding is that this issue is specifically asking to add a clickable ¶ symbol next to each subheading.

Exactly, as per the original description:

Each subheading to be a link such that hovering over it (the heading) a ¶ symbol should appear, like on godoc:

Clicking that link should then change to the address bar URL to include the fragment. For example on godoc, for the "Benchmarks" subsection we end up with the URL:

@gopherbot gopherbot added this to the Unreleased milestone Feb 6, 2020
@julieqiu julieqiu added NeedsFix The path to resolution is known, but the work has not been done. and removed NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Feb 29, 2020
@julieqiu julieqiu mentioned this issue Mar 12, 2020
Closed
19 tasks
@dmitshur dmitshur self-assigned this Mar 23, 2020
@dmitshur
Copy link
Contributor

I've sent a CL that should fix this issue once it is deployed. We can keep this issue open to confirm everything is working as expected.

@dmitshur dmitshur changed the title go.dev: add ability to link to package doc subheadings go.dev: include '¶' permalinks in all package doc subheadings Mar 24, 2020
@tooolbox
Copy link

This is super important, thank you @dmitshur !

@dmitshur
Copy link
Contributor

This fix has been deployed and it's working as expected. For example, see:

image

Note that it may not appear on some existing package versions until they've been reprocessed, but they should work on all new versions. Please let us know if you spot any other issues.

gopherbot pushed a commit to golang/pkgsite that referenced this issue Jun 15, 2020
@dmitshur @julieqiu
internal/fetch/dochtml/internal/render: insert '¶' permalinks in head…
5921372 
…ings

Make it an option that can be toggled, so it is easier to tell that
this feature is different from the original CL 72890. This option
can be deleted later when there are fewer godoc variants and the
flexibility it offers becomes no longer needed.

This package is internal, so changing its API can be done at any time.

Background

The render package was initially developed in the context of the
golang.org/x/tools/cmd/godoc command. That command historically
used the ToHTML function from go/doc package, which did not have
functionality to insert permalinks for headings. That functionality
was later implemented in https://golang.org/cl/33641 on the frontend
using JavaScript.

It was done on the frontend because modifying the go/doc package was
slow, and because the intent was to make a change affecting the entire
golang.org website.

Here, we have full control over the documentation HTML rendering, so
it's easy to implement this functionality on the backend for the needs
of the discovery site.

Fixes golang/go#36808.

Change-Id: Icb0210f9e0870a7bbf80e0aa80ba2e6421177ba8
Reviewed-on: https://team-review.git.corp.google.com/c/golang/discovery/+/698511
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Julie Qiu <julieqiu@google.com>
@julieqiu julieqiu modified the milestones: Unreleased, pkgsite/dochtml Aug 19, 2020
@golang golang locked and limited conversation to collaborators Aug 19, 2021
@hyangah hyangah added the pkgsite/dochtml Issues related to package documentation in pkgsite label May 20, 2022
# for free to subscribe to this conversation on GitHub. Already have an account? #.
Assignees
No one assigned
Labels
FeatureRequest Issues asking for a new feature that does not need a proposal. FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done. pkgsite/dochtml Issues related to package documentation in pkgsite pkgsite
Projects
None yet
Milestone
pkgsite/dochtml
Development

No branches or pull requests
6 participants
@dmitshur @myitcv @tooolbox @hyangah @julieqiu @gopherbot