🗳 Add new table-of-contents validator

[agoose77]

In #1102, we identified the need for a new table of contents format.

This format must satisfy the following goals:

1. Easy to humanly read/write
2. Easy to programatically read/write
3. Expressive enough to represent complex trees

This PR is a WIP in that direction. The TOC schema can be build using

npm run build:schema --workspace=packages/myst-toc

and then used with https://www.jsonschemavalidator.net/ (or the CLI equivalent) to verify a TOC JSON blob.

Here's an example "complex" TOC:

  - title: Main
    file: main.md
  - title: Overview
    children:
      - file: overview-1.md
      - file: overview-2.md
  - url: https://google.com
  - file: getting-started.md
    children:
      - file: getting-started-part-1.md
      - file: getting-started-part-2.md

There are notably two kinds of "subtrees" in MyST:

1. Non-hyperlink categories (grouping)
2. Categories with index pages (Sphinx-like)

This TOC supports both; a bare children entry requires a title, whereas a file/URL entry does not.

@rowanc1 also mentioned the ability to choose between drop-downs and fixed-headings. This TOC format has a class string field that we could use to support that.

We should iterate on this as necessary!

Closes #1102

[rowanc1]

Looking good, some thoughts below as I go through this.

Some of the things we can maybe choose to add:

• id: be able to reference a part of the toc
• numbered: (maybe numbering?) We have had a lot of requests to have full-book numbering rather than per page. This is a step in that direction, I think that numbered would be validated to numbering as well (defined in frontmatter already, important for figure: start: 5 and enumerator: 1.%s), which has the enumerator to be used on the page.
• part? Something to indicate that this is a chapter, appendix, or dedication, etc. I think this is different than a class, which is about visual styles. This would be helpful for placing in templates.
• hidden

Options like glob can be read at validation time, and coerced into this format. Also implicit folders, similar to the default behaviour now.

Is there some way to apply default classes? i.e. a top-level kind: book-sections? Or do we want people to write class: heading on each? Maybe this is also validation/coersion to this format? I am not sure what the ajv validation is used for in that case - if the user is never interacting with this format?

[agoose77]

Notes from a meeting on this:

• We don't need a root document; we can use the first document (array of entries).
• part should be singular, we can pluralise it later if needs be
• numbering needed, should inherit?
• id needed for all entries
• Normalise pattern entry type to array of file, don't use internally after normalisation.
• hidden needed, should inherit
• class and classes are plural vs singular
• We want to define the numbering style in future, as a style-field?

[agoose77]

@rowanc1 I've updated this PR to add id, hidden, part fields to all entries. We don't have class on all entries; right now it's limited to parents. Is that reasonable, or do we have need of it on every entry?

[agoose77]

@rowanc1 the schema generator has a dependency on NodeJS>=18 due to structuredClone. What are your thoughts here; it's only a development dependency, we probably want to try and patch it right?

[rowanc1]

I think that we could drop node 16 actually and start testing 22. We should do that in another PR and update a few parts of the docs and the min version.

[rowanc1]

I think class makes sense on every node? Thinking about that beta-feature example with a custom icon in the TOC which exists only on a child.

[rowanc1]

@agoose77 #1162 is merged if you want to rebase here and get the tests passing?

[agoose77]

@rowanc1 is this good to go in your view? If so, feel free to merge! The plan is that another PR will hook this into the config side of MyST-MD

[rowanc1]

I will take it for a spin this afternoon and get it in and released!

[rowanc1]

The types look good here. I think things will change a bit when we integrate it with myst-frontmatter, but that can happen in the next iteration.

[rowanc1]

It would be nice to get nicer errors here to show to users. I suspect when we integrate this into myst-frontmatter, we will use the simple-validators as that does now, which will allow us to have coercion and better validation messages that work with where we are at now.