Add section headers to navigation element

[bvaughn]

This issue was originally opened by @donpinkus via facebook/react/issues/10980

The side-nav only displays page titles. It would be nice if it also displayed section headers for the current page:

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.

[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).

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).

[el1f]

This issue doesn't seem relevant anymore since now the docs provides header based navigation.