Automatic Wiki TOC with Manual Override

TOCs are Good / TOC Maintenance is Not So Good

It is good for a wiki to have a Table Of Contents (TOC). A tree structured organization of content.

Such TOC's are convenient for readers. In particular for readers who want to study all or at least a large part of the content.

It is a pain to have to manually maintain such a table of contents.

Many of the interfaces to automatically generate such a table of contents are suboptimal. E.g. in Atlassian's Confluence wiki, you can set a parent for a page, and there is a GUI where you can drag pages and subtrees around and play some beneath other pages. But it can be a pain to have to set these things up.

Then, of course, there is a question of how to arrange or sort the list of pages and/or subtrees beneath any particular parent node.

My Old Twiki Tool for TOC Tree Management

My old twiki tool started off fully automatic. But instead of dividing the tree structure with the page leaf items, it would generate a TOC tree, with links to the pages. If no tree structure was obvious, a flat list.

Original Unordered Collection of Pages

• klpjkjk
• root topic
• topic2
• kljh uhh
• topic1
• jklhh
• kljj
• iojho

The human (me) could edit that tree structure.

• root topic
  • topic1
    • subtopics: kljh iojho uhh
  • topic2
    • subtopics: jklhh kljj klpjkjk

Thereafter, the tool would respect the manual editing, but it would add automatically add nodes that were not already in the TOC tree, e.g. for newly added pages. One heuristic was that such a new page would be added to the tree as a child of the first page in the existing talk tree that referenced it. Other heuristics might choose as parent the referencing no closest to the root, airing common tags, etc. such automatically added pages were distinguished from manually organized pages. And of course any automatically added page could be reordered manually.

TBD: I need to re-create this TOC tree tool for the GitHub wiki

• The Usual Good Stuff*: of course, you want aspects of the TOC tree structure to be reflected as links inside the pages, such as Up/Next/Back.

Q: should such navigation links inside the page be manually edited within the page? this could interfere with automatic generation. I would hesitate to completely override the overall TOC-tree, but pointing out inconsistencies might be desirable.

Note that you can have several TOC-trees for the same set of pages, whether the full set, or overlapping subsets. So such navigation links might has several different flavors or groupings Within the same page presented to the user. Or, the actual content page might be wrapped or framed by a page that that has the navigation links of one or multiple flavors.