Table of Contents

[Gazook89]

There was a bit of chatter about TOC's this week, and I couldn't find a general purpose PR or Issue (or at least one that wasn't imminently closing or publishing) that could collect the ideas.

I think there are a couple of general complaints related to the current TOC process:

1. No way to know what the outcome is really going to look like on first try-- it doesn't seem to collect any info, so there is no way to guess what is going to return.
2. Cannot set header depth (only option is h1, h2, h3).
3. Collects headers regardless of where they appear in the page
4. No way to exclude headers manually (particularly for users who don't use headers semantically).
5. "One and done"...difficult or tedious to edit once generated, and annoying to have to regenerate and fix again.
6. At least some level of expectation that the ToC would keep pace with new or deleted headers as edits are made.
7. More difficult rules than the average CSS rules is a hurdle for novice CSS'rs. Setting column counts, leader lines, fonts, indents, etc.
8. ToC goes to second page, but new page isn't created, and if a new page is created the page numbers will be off from the TOC.

---

Some of this could be done with CSS inputs in the TOC Widget menu. Things like column counts, leader lines....

One thought: A ToC Panel that is a tab in the Editors. It dynamically updates with the document, can be used for hyperlink navigation, updates page numbers as they change, has CSS inputs to toggle leader lines, set column counts and fonts, and has additional parameters that change header depth and how many pages to allow for the TOC. From here the author can print the ToC markdown to the Text Editor and the required CSS to the Style Editor, or alternatively, have the required CSS for the various choices baked into the build folder and then snippet would just print the ToC Markdown with some relevant classnames to match the desired properties.

The same ToC panel could be made available in the Share page as a sidebar, for easier and more reliable navigation than scrolling to the top for the ToC (which might not even be there).

Edit:
Issues related at this time:
#2920
#2905
#2563
#2885
#2686
#2294

[Gazook89]

[ericscheid]

See also #2840

[Gazook89]

Here is another mockup of a ToC tab which shows the addition of a search box, for searching the full text and offering a "jump to page". This would work by searching the position in the markdown rather than in the rendered preview. And some ToC settings can be set here.

Two zoomed out versions, showing an alternate placement of tabs on the /edit/ page and the /share/ page (which would also have the Brew Info area moved to a splitPane panel):

[dbolack-ab]

Going this route, would we drop a "Table of Contents" brew variable in the brew text that would pour the same data ( maybe in a different shape? ) ?

This would eliminate the need for the snippet?

[5e-Cleric]

We would still need the snippet, as the pdf will need a table of contents.

[dbolack-ab]

Is the idea here to put a widget interface on top of the present incarnation of the ToC snippet?

[Gazook89]

Not so much on top of the snippet. My thought initially is that this would just be a place to view an existing table of contents that had been generated. Basically building up a little html structure of the brew headings like we do for the snippet generation, but as html. Each heading would be a link to the correct page/heading in the preview pane.

The inputs at the top would allow a user to make changes to how the toc was generated. However, as I am looking at it again now, these inputs don't make much sense if it's just a TOC viewer. So likelky I had some thought that this could be used to dynamically generate a TOC.

If I had to guess my intentions: Perhaps a special div in the brew marked ToC is placed in the Brew Editor. Then, you could set your TOC settings in this panel and then submit it, to generate a TOC where that special div is.

[5e-Cleric]

So a snippet widget, permanently open to allow for navigation?