New docs site - Add section headers to navigation element

[donpinkus]

In the new Reactjs.org docs, the nav only has different pages. This makes it very difficult to quickly find / jump to a part of the docs you care about.

If this change would be accepted, I'll create the PR for it.

For example - what are the life cycle events in React?
The closest thing in the nav is "Quick Start > State and Lifecycle". After navigating to this page, and reading for a few seconds - it becomes clear this is a tutorial. Is there a list of the lifecycle events? I'm not sure. I scan through the whole page. Doesn't look like it, but maybe I just missed it.

Repeating this process of scrolling through entire pages is time consuming, so instead I just google "react 16 lifecycle events" and end up finding it on someone's independent blog post.

[noinkling]

Related, if this gets implemented I think the nav should also have some sort of scrollspy to make it apparent which (sub)section you're on. The lack of it is already noticeable in the tutorial (the section that was initially clicked on stays highlighted no matter where you are in the document).

[bvaughn]

I'm slightly against this proposed change because- at the moment- it would more tightly couple the side-nav YAML config files to the markdown content. As it is, changing an article title (in markdown) or adding a new markdown file requires someone to remember to also update the YAML file. This proposed change would require more edits (to ensure that anchor tags stayed in sync).

Ideally I would like to actually remove those YAML files entirely and have the side-nav be generated programmatically based on markdown content. At this point it would be possible to add section headers (although I'd love to hear @joecritch's opinion on the UI/UX of this).

[bvaughn]

Related, if this gets implemented I think the nav should also have some sort of scrollspy to make it apparent which (sub)section you're on. The lack of it is already noticeable in the tutorial (the section that was initially clicked on stays highlighted no matter where you are in the document).

This has always been on our roadmap for the Tutorial 😄 Just haven't had time to add it yet. There's an issue for this FWIW (#10984).

[joecritch]

From a UI perspective, I dig this. I think it provides more focus and context. The reason I introduced an accordion for the sidebar's sections was for a similar reason, and I think this complements it well.

So yeah, if the sidebar can be generated based on the Markdown, as @bvaughn suggested, this could work? (Although some articles will need their document outlines sanitizing.)

[bvaughn]

Thank you for filing this issue! 😄

The documentation and source code for reactjs.org now lives in a different repository: reactjs/reactjs.org. (For more info on why we made this move, see issue #11075.)

I've moved your issue to the new repo: reactjs/react.dev#20

Let's continue the discussion there! Sorry for the inconvenience.