docs: Highlight reader's position in table of contents #1262
Conversation
While browsing the documentation, I often become disoriented because the table of contents is so long, and there's no connection between it and the content I'm viewing. To make it easier for readers to orient themselves, navigation links in the table of contents are emphasized when their respective section is being viewed by the user. To accomplish this, `<section>` tags have been wrapped around all the content. (I also took the liberty of using `<article>` and `<nav>` where it was appropriate.) When the page's DOM is loaded, some JavaScript runs that: 1. Creates an [`IntersectionObserver`][1]. 2. Queries all the navigation links in the table of contents. 3. For each link, associates it with the destination section. 4. Passes each section to the `IntersectionObserver`. When a section moves in or out of the viewport, a callback adds or removes a `visible-section` class to the associated navigation link. Known Issues: - To be consistent, `header_open|close` should probably be renamed to `section_open|close`. I have not done that yet since it would bloat the diff and make the functional changes harder to review. - Chrome seems to shrink headers right after a `<section>`. It looks a bit odd, so some CSS might be needed. [1]: https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver
|
Thanks for the PR. I'll have a look at this on my phone tomorrow or Monday and then merge this. |
|
Just thinking out loud here, I think it would be nice as well, to have a css-only thing where a section link icon appears so you can copy the link of a header. GitHub has this if you mouse-over a header in a README. |
|
I played around with this a little bit in Firefox. It's glitchy. The bold doesn't always show up. It's probably an issue with IntersectionObserver and not your JavaScript code. Even so, I think I'd like to move in the direction of less JavaScript rather than more for the language reference. If there's some non-hacky CSS-only thing we can do to make the TOC nicer let's do that. But let's not add JavaScript which is just supposed to make stuff bold. I plan to eventually remove the syntax highlighting javascript and replace it with statically colored html. I'm going to close this. I agree with the problem statement - disorientation between the TOC and the content - however I don't think this solution is better than status quo. I'd like to propose a non-javascript alternative solution to the problem.
|
While browsing the documentation, I often become disoriented because
the table of contents is so long, and there's no connection between it
and the content I'm viewing.
To make it easier for readers to orient themselves, navigation links in
the table of contents are emphasized when their respective section is
being viewed by the user.
To accomplish this,
<section>tags have been wrapped around all thecontent. (I also took the liberty of using
<article>and<nav>where it was appropriate.) When the page's DOM is loaded, some
JavaScript runs that:
IntersectionObserver.IntersectionObserver.When a section moves in or out of the viewport, a callback adds or
removes a
visible-sectionclass to the associated navigation link.Known Issues:
header_open|closeshould probably be renamed tosection_open|close. I have not done that yet since it would bloatthe diff and make the functional changes harder to review.
<section>. It looksa bit odd, so some CSS might be needed.