Add a new table of contents format

[agoose77]

Proposal

Add a new table-of-contents format to live inside myst.yml. This will supersede the _toc.yml which is strongly constrained by the design of Sphinx (sphinx-external-toc).

Additional notes

This format should be readable, easy to guess, and support styling markup (e.g. dropdown vs header)

[rowanc1]

@choldgraf I would be curious on your take on @agoose77's proposal that we went through on Monday and I think is pretty close.

I always have a lot of difficulty in working with the current TOC, and there is a lack of flexibility and confusion on where to use the keywords of part chapter section and caption. Every time I use it I have to bring up the docs and it is difficult or impossible to do certain things. (e.g. have headers inside of nested elements, a section that is a dropdown and a link and styled a certain way, etc.).

The goals that @agoose77 @fwkoch @stevejpurves and I discussed was a new toc format that: (1) is easy to understand, move around (e.g. unindent the yaml, no changing of key-names from chapter -> part); (2) the root isn't special, it is just a page; (3) can support parts for book exports in a more robust way (e.g. this is the abstract, this is an appendix); (4) supports easy access to styling; (5) can be added directly in the project config; (6) has the ability to do partially implicit contents based on files/folders/pattern matching; (7) sets us up to be able to render part of the toc in the document, based on a label similar to anything else. (8) support for numbering across an entire resource (currently numbering restarts on each page in the website).

I think the new format that @agoose77 mocked up is hitting those. Are there things we are missing as ways to set that up?

[choldgraf]

Based on your list of goals above, and the fact that you think we are hitting them, I think that this is safe to merge and play around with to see if our understanding of this changes as we use it. We could make this as an alpha feature and then try it out. As is, I don't see anything that should be a blocker (other than perhaps more comprehensive docs to cover all the things you mentioned!). It looks great!

One thought I had as an example: I wonder if we will regret not having semantic tagging (part or chapter) in some export conditions, like latex. I don't know it will be the case though, and I think we will only learn once people try it and open issues that suggest this level of control would help rather than hinder. In the absence of that data, however, I think simpler is definitely better!

[roaldarbol]

I really like the idea of the new TOC, especially having it in myst.yaml, and the free levels. For template support it would be nice with the option to name levels. So the names (e.g. part, chapter) could be unrelated to the nesting level, but assigned - so you could specify that level 2 would be part.

toc-nesting: [part, chapter]

It could also allow users to create theor own naming convention which might be good for their own use cases.

Am on mobile, so apologies if this makes little sense.

[rowanc1]

Thanks for jumping in @roaldarbol -- I am having a bit of difficulty fully understanding your suggestion. I would like us to have another think on this from the PDF export and ensuring that we are supporting the right level of nesting (i.e. to support latex chapter/part/section stuff). I know that @fwkoch has been able to do this internally in our book exports so far, and there are no labels for part/chapter at this stage, I forget how that is done though!

[roaldarbol]

Yeah sorry wasn't very clear - and on second thought it might not be an issue. All I want is to retain the ability to say "this document is a part" or "this document is a chapter" somehow, to let the nesting be explicit in some way if /when needed. But I guess the +++ fences would specify that, right?

[choldgraf]

Just a general point here: I think our goal should be to ship an MVP, and make sure we aren't accidentally closing any important doors in the process, with the goal of getting it into people's hands and iterating from there.

So my question re: part, chapter, etc is: could we iteratively add that functionality later if we wanted to? If so, let's just get this in and start playing with it so that we gain better intuition for how it could be better.