Provide tree of headings in @island/headings

[dhruvkb]

Is your feature request related to a problem? Please describe.
Since the @islands/headings packages provides headings as a list, instead of a tree, I am unable to render a proper tree in the table of contents.

Describe the solution you'd like
I would prefer that during parsing of the AST, headings be compiled into a tree-structure instead of (or in addition to) a list so that the relationships between headings is also available in the post.meta field.

Describe alternatives you've considered
This could be accomplished by a separate plugin but a lot of the code would be duplicated between the @islands/heading module and the separate one.

Additional context
Having the headings as a tree would make it possible to index the headings and provide meaningful numbering to them as well. For example, something like this would be possible if the headings were a tree.

§1 Chapter
  §1.1 Section
  §1.2 Section
    §1.2.1 Subsection
§2 Chapter
...

I'm happy to make a PR if this change seems useful to the general user base.

[ElMassimo]

You can already create a tree structure from the list of headings.

Would you describe what structure you would expect to see when using "tree mode"?

[dhruvkb]

I extended PageMeta to inherit from the interface NestedHeading.

export interface NestedHeading {
  subheadings: NestedHeading[] // contains headings that are children of this one
  indices: number[]            // useful for building numbered chapters, sections etc.
}

This way I can recursively iterate over subheadings field and build the tree of headings when parsing the AST. Each node also has a data-indices attr injected on it which is indices.join('.'), and I am using CSS to prefix the §x.y.z before it.

[ElMassimo]

I see your point about creating a separate module:

a lot of the code would be duplicated

Given that this feature seems reasonably common, it might make sense to include this in @islands/headings out of the box, under a nested: true opt-in setting (or similar).

Feel free to make a PR, and we can discuss what the API would look like. Thanks!