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

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

Open
bcmills opened this issue Dec 22, 2020 · 3 comments
Open

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

bcmills opened this issue Dec 22, 2020 · 3 comments

Comments

@bcmills
Copy link
Member

@bcmills 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 the pkgsite label Dec 22, 2020
@gopherbot gopherbot added this to the Unreleased milestone Dec 22, 2020
@bcmills bcmills added the UX label Dec 22, 2020
@julieqiu
Copy link
Contributor

@julieqiu julieqiu commented Dec 23, 2020

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

@bcmills
Copy link
Member Author

@bcmills 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
Member Author

@bcmills 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants
You can’t perform that action at this time.