Add a table of contents to rendered notebooks

[isabela-pf]

Problem and context

This issue comes from our user testing round 1: navigation. Several participants remarked upon the lack of visible table of contents at the top of the notebook. Based on the feedback, this sounds like a standard expectation (though one not always met) for these participants whenever they are navigating a document-focused interface. While this missing piece of UI did not prevent any participants from being able to complete their tasks, it was mentioned many times that the tasks' workflow would be improved with a table of contents.

This was requested most frequently for navigation, content summarization, and notebook metadata (ie. what info participants rely on to know they are in a notebook with “helpful” information for their task). Participants also mentioned that this becomes extra important the longer a page/document is.

The added table of contents needs the following qualities.

• To either be early on/near the top of the page (ie. a cell at the top of the notebook), or to have a fixed place in the interface that is easy to get to (ie. a side bar)
• To match the content headings of the notebook as they are written by the author
• To link directly to each content heading (a plain list will not suffice; it needs to be interactive)
• To have some way to quickly return to the table of contents when in other areas of the document

As a note, this was requested almost entirely by participants who did not use a screen reader during their session. Some participants who did use a screen reader during their session did request it. Of screen reader-using participants who did not request a visible table of contents, all of them used content heading navigation via their screen reader to complete at least one task (and some used it for all tasks).

Possible solutions

• Add the table of contents as an autogenerated cell near the top of the notebook. Because this information is being properly output into HTML (because screen readers were reliably able to access and navigate the headings), it would be a matter of taking that existing output and placing it in its own cell.
• Add the table of contents as an author-generated cell near the top of the notebook by adding to the STScI notebook template. This would be the fallback method and would require us to update notebooks manually. I would not advise this approach unless we cannot find another method. (I'm not sure how easy it is to find/access the heading links prior to converting the notebook, either.)
• Add the table of contents as an autogenerated, new header area of navigation in the document.
• Add the table of contents as an autogenerated, new sidebar navigation in the document (a la many default documentation themes or the JupyterLab table of contents)
• Some other cool idea you have!

Acceptance criteria

This issue can be closed when we

• Merge a PR that adds the infrastructure for a table of contents to the desired upstream repo

Tasks to complete

• Reach agreement about what table of contents-generating method we want and where those changes will be made
• Propose visual designs, critique and iterate on visuals as needed
• Make code changes where needed
• Get work merged

[isabela-pf]

In Task 3, participants were asked "If you were able to magically make accessing this section [File Information] easier, what would be the same? What would be different?" One participant specifically noted the way they like to navigate through content headings (ie. a new topic of discussion, the next step in a tutorial as denoted by HTML heading attributes) using the number keys 1–6, a heading navigation control on JAWS for Windows.

I need to verify if this was because the user could not complete this as-is and wanted to, or if it was a clarifying note that we should make sure to test when working on content heading navigation elements like a visible table of contents. Either way, the specificity of the feedback warranted an extra note.

Because this was a discussion about content headings, I am adding it to this issue. If we end up needing different fixes, let me know and I can move it elsewhere.