Skip to content
New issue

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

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

Already on GitHub? Sign in to your account

Jump to bottom

x/pkgsite: navigation bar loses heading structure from README #43325

Closed
bcmills opened this issue Dec 22, 2020 · 8 comments
Closed

x/pkgsite: navigation bar loses heading structure from README #43325

bcmills opened this issue Dec 22, 2020 · 8 comments
Labels
FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite/frontend Issues related to pkgsite HTML/CSS/JavaScript and frontend development pkgsite UX Issues that involve UXD/UXR input
Milestone
pkgsite/frontend

Comments

@bcmills
Copy link
Contributor

bcmills commented Dec 22, 2020

What is the URL of the page with the issue?

https://pkg.go.dev/github.com/mattn/go-sqlite3

What is your user agent?

Mozilla/5.0 (X11; CrOS x86_64 13505.73.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.109 Safari/537.36

Screenshot

image

Compare to the README as rendered on GitHub:

image

What did you do?

Examine the headings on the left navigation bar.

What did you expect to see?

A clear distinction between topics (h1) and subtopics (h2).

What did you see instead?

The pkg.go.dev navigation bar does not visibly distinguish between topics and subtopics.
@gopherbot gopherbot added this to the Unreleased milestone Dec 22, 2020
@bcmills bcmills added the UX Issues that involve UXD/UXR input label Dec 22, 2020
@julieqiu
Copy link
Member

Thanks for the feedback!

We decided to flatten the hierarchy because users like to do a lot of different things with their README headings.

Some examples:

  • skip levels (github.com/google/uuid has only h1s and h6s, github.com/sirupsen/logrus has only h1s and h4s)
  • multiple h1s (github.com/spf13/cobra and github.com/mattn/go-sqlite3 have multiple h1s)
  • no h1s (github.com/googleapis/google-cloud-go/tree/master/storage starts at h2)

We currently show the highest and second highest levels in the TOC for the README section.

If you have suggestions on how to better surface this information, let us know!

/cc @jamalc @georgehu @fflewddur

@julieqiu julieqiu added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Dec 23, 2020
@bcmills
Copy link
Contributor Author

bcmills commented Dec 23, 2020

I agree that it does make sense to compress the observed heading range and prune out levels that appear to be too fine-grained.

But, rather than flattening the levels that are included, I would like them to be visually distinct in some manner. That could be implemented as different indentation levels, different background colors, different font weights and sizes, or perhaps some other mechanism — the important thing is that they be distinct in some easily-observable way.

@bcmills
Copy link
Contributor Author

bcmills commented Dec 23, 2020

For skip-levels in general, I agree that showing the highest 1–2 levels in the ToC seems reasonable.

I have a few other suggestions for that heuristic, but in my opinion none of these suggestions is as important as making the heading levels visually distinct. 🙂

  • If the document has only one of the highest headings and it appears only once and before all other headings, we could treat it as a de-facto page title and display it alongside (or instead of) the word “README” at the top of the page and the top of the ToC, rather that treat it as a section within the ToC.

  • We could choose the number of levels to retain based on the number of headings in the document so that, if possible, the resulting ToC will typically fit above the fold no matter how many sub-headings are used.

  • We could enclose the ToC and the links below it in some visually distinctive manner (such as a background color or an outline), so that if it does spill below the fold users will have a visual indication that they may need to scroll down to see some of the relevant links. Or, if the ToC doesn't fit above the fold perhaps we could collapse it into a <details> element.

@robpike robpike mentioned this issue Feb 1, 2021
Closed
@gopherbot
Copy link

Change https://golang.org/cl/309393 mentions this issue: internal/frontend: extract nested table of contents from markdown

gopherbot pushed a commit to golang/pkgsite that referenced this issue Apr 14, 2021
@jamalc
internal/frontend: extract nested table of contents from markdown
df7a615 
The processReadme function now returns a nested table
of contents extracted from the readme file based on
the hierarchy of headings in the document.

If the document has only a single top level heading
and that heading has children it is assumed to be a
title and removed from the table of contents.

For golang/go#43325

Change-Id: I5b67a7e356820477851e6c34493e2517f889b02f
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/309393
Trust: Jamal Carvalho <jamal@golang.org>
Run-TryBot: Jamal Carvalho <jamal@golang.org>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Julie Qiu <julie@golang.org>
TryBot-Result: kokoro <noreply+kokoro@google.com>
@gopherbot
Copy link

Change https://golang.org/cl/310131 mentions this issue: content/static: readme outline reflects heading structure from markdown

gopherbot pushed a commit to golang/pkgsite that referenced this issue Apr 14, 2021
@jamalc
content/static: readme outline reflects heading structure from markdown
52c38d2 
The structure of the headings in the readme is now reflected
in the readme outline up to three levels of depth.

For golang/go#43325

Change-Id: Iee639fea299e93bfd5223dac3a50b663ce0ca89b
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/310131
Trust: Jamal Carvalho <jamal@golang.org>
Run-TryBot: Jamal Carvalho <jamal@golang.org>
Reviewed-by: Julie Qiu <julie@golang.org>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
TryBot-Result: kokoro <noreply+kokoro@google.com>
@jamalc jamalc self-assigned this Apr 15, 2021
@gopherbot
Copy link

Change https://golang.org/cl/310371 mentions this issue: content/static: move mobile outline container to frontend template

@gopherbot
Copy link

Change https://golang.org/cl/310372 mentions this issue: content/static: add readme outline to mobile nav

gopherbot pushed a commit to golang/pkgsite that referenced this issue Apr 15, 2021
@jamalc
content/static: move mobile outline container to frontend template
44ea98d 
The container for the mobile outline was part of
a template used in the dochtml package making it
difficult to extend from the frontend. Limiting
the dochtml sidenav-mobile template to the minimum
necessary html will allow us to add the readme
headings to the mobile outline. This change moves
the non-dochtml html to a new file to do just that.

For golang/go#43325

Change-Id: Ieef429034e7082215bd2cdb75bbf88f30683cf96
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/310371
Trust: Jamal Carvalho <jamal@golang.org>
Run-TryBot: Jamal Carvalho <jamal@golang.org>
TryBot-Result: kokoro <noreply+kokoro@google.com>
Reviewed-by: Julie Qiu <julie@golang.org>
gopherbot pushed a commit to golang/pkgsite that referenced this issue Apr 15, 2021
@jamalc
content/static: add readme outline to mobile nav
217d00d 
Adds top level readme outline headings
to the mobile select dropdown nav.

For golang/go#43325

Change-Id: Ib2664838303e4b4bcbf54967253f10aa036706f3
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/310372
Trust: Jamal Carvalho <jamal@golang.org>
Run-TryBot: Jamal Carvalho <jamal@golang.org>
TryBot-Result: kokoro <noreply+kokoro@google.com>
Reviewed-by: Julie Qiu <julie@golang.org>
@jamalc
Copy link

jamalc commented Apr 15, 2021

These changes are now live.

@jamalc jamalc closed this as completed Apr 15, 2021
@golang golang locked and limited conversation to collaborators Apr 15, 2022
@hyangah hyangah added the pkgsite/frontend Issues related to pkgsite HTML/CSS/JavaScript and frontend development label May 20, 2022
@rsc rsc unassigned georgehu and jamalc Jun 23, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite/frontend Issues related to pkgsite HTML/CSS/JavaScript and frontend development pkgsite UX Issues that involve UXD/UXR input
Projects
None yet
Milestone
pkgsite/frontend
Development

No branches or pull requests
6 participants
@georgehu @hyangah @bcmills @julieqiu @gopherbot @jamalc