thoughts on ocular TOC generation

[jckr]

those are my notes as I'm researching better TOC generation for ocular.

First, it makes no sense to have a chapter notion different from entries. they are functionally the same and they just complicate the graph.

(What we could have is a notion of tree in the TOC. in some "legacy" ocular sites (ie vis.academy) we have several independant TOCs ie you can't navigate from a page described in one TOC to the next. those trees all have different entries in the header menu (or elsewhere). That's a P1 though)

If we use the onCreateNode callback, we can access the TOC node as it's created and directly mutate it. The problem is that the function we'd use relies on a docNodes object, which is half populated by then.

The alternative is to work at the createPages level, where we execute a graphQl query. But then, we no longer have access to the TOC node / we can't mutate it directly.
However, we can have the same information as a result from that query. If we can access the TOC node then great, else we'd have to create a new node and pass it the relevant information.

[ibgreen]

I am not quite sure what the proposal is.

• I think that you are saying that we should allow an "entries" to recursively contain "entries" and do away with the "chapters" concept? (seems like a reasonable simplification).

• I don't think that are you proposing that we drop the table-of-contents.json and just work with auto discovering directory nodes?

FWIW, I will add a requirement: I'd like to be able to link in docs that are in multiple doc trees (rather than just in one /docs root.

The reason is that we are increasingly modularizing our repos with multiple code bases into monorepos with modules structure:

modules
  module1
     src
     test
     data
     docs???
     package.json
     README.md

We are collecting everything related to that module inside that folder, except the docs, and for big repos it gets hard to track and keep the docs correct when they are in deep subfolders in a different structure.

[jckr]

those are just notes as I try to get the TOC generation to work.
Yes, I think we should drop entries/chapters. it should all be entries or chapters.
Regardless, we can't have an infinitely nested TOC. This graphql issue makes a point. graphql/graphql-spec#91
But we can go 3/4 levels down. It would be easier with something like

entries {
   ...entriesFragment
   entries {
        ...entriesFragment
        entries {
              ...entriesFragment
              entries {
                   ...entriesFragment
              }
       }
   }
}

than if we have to accommodate every arrangement of chapter / entries.

For multiple trees, I don't recommend dropping table-of-contents. I just feel the TOC could instead be:

[
{
tree: 'documentation', // default name
entries: [...]
},
// optionally other trees
]

and that the TOC component would only display entries for one tree at a time. It would definitely be possible to go from one documentation page to another, via a link, regardless of its tree. the tree distinction is only to display one TOC at a time.

Alternatively we could add a tree field to entries with children and only display entries of the current trees.

This tree business is a further development, while it would be necessary to convert some of the sites that's not something I want to have resolved now.

[jckr]

Back to the generation of TOC in onCreateNode vs along the createPage calls.
I can create a node after the graphQl query in the createDocPages function, ie

createNode({
    id: 'new-toc',
    internal: {
      type: 'DocsJson',
      contentDigest: 'generated toc',
    }
  });

However, I'm not able to find that node with subsequent graphQl queries.

So I'm considering a third approach - back in onCreateNode.

Right now, what happens is that we don't know the order in which nodes are created. It can be:
M, M, M, M, M, J, M, M, M, M (where M is markdown and J is json).

when the J node is treated it assumes all M nodes have been already treated.

What we can do instead is:

• when an M node is treated, it adds itself to docNodes. If no tocNode object exists, no further action.
• when a J node is treated, it uses the existing docNodes to go as far as it can. Basically the only thing the table of contents needs from from the corresponding M node is:
  • the slug (from fields/slug)
  • the title (from frontmatter/title)
    But the full traversal of the table of contents can be achieved though we can't guarantee we can populate these fields for all nodes.

Finally, when an M node is treated AND a tocNode exists, then we can add the slug and the title information at the right places in the tocNode.

So, at the end of this process, all nodes should have the required information regardless of the order

[jckr]

closed with #103