Auto TOC in XWiki (second try)

[vmassol]

Hi Devs,

Context

I was trying to clean some jira issues and we have several related to the concept of having some kind of auto toc in XWiki (ie an automatically-generated TOC somewhere, for each page, without needing to manually insert the TOC macro).

This thread is basically a respawn of Auto TOC in XWiki? (first try) but asked a bit differently.

Decisions

I’d like us to decide what we’d like to do and close the jira issues we don’t want to implement. I’ve listed several points below and am interested in your opinion for each line.

1. Do we need this feature in XWiki or is the manual TOC enough? ie should we close Loading... as won’t fix or not.

Assuming we want an auto toc in XWiki:

2. Should we provide it as a rendering transformation (with some configuration option similar to heading numbering to turn on/off), ie should we close Loading... as won’t fix or not.

3. Should we provide it as tree nodes inside the Document Tree macro (for perf reason, it would always be folded and when the user clicks an arrow to open it, leaf entries are generated for each heading. Note: we would need to render the document to have perfect results. Since the Navigation tree panel is visible on all pages, it would provide a way to quickly navigate to headings in documents.

4. Should we provide it as a TOC Panel, ie should we close Loading... as won’t fix or not?

5. Should we provide a UIXP somewhere (example in the following screenshot), folded by default and when clicked, it would display the TOC for the page:

6. Any other option?

So WDYT?

My answers

1. I don’t remember being asked recently about such a feature so I’m tempted to say that we don’t want it in XWiki. Ofc everyone is free to do it in a contrib extension and we could even provide some new UIXP if one is missing. This means that I’d be in favor of closing all 3 jira issues referenced above as won’t fix.

2. No

3. Maybe, but I have a preference for 5 (which is located inside the page content and doesn’t require a new rendering)

4. No

5. Yes

Thanks

[mleduc]

@vmassol

I don’t remember being asked recently about such a feature so I’m tempted to say that we don’t want it in XWiki. Ofc everyone is free to do it in a contrib extension and we could even provide some new UIXP if one is missing. This means that I’d be in favor of closing all 3 jira issues referenced above as won’t fix.

+1 for that option, until somebody requests this again with a use case.

[nikpetrenko]

I’m not a fan of ToC even if a page will have 5-6 headings 2nd level with subheadings. As long as the section text contains only a few meaningful paragraphs, I do not have difficulty navigating or searching for content. That’s why my personal preferences do not add (or even generate) ToC.

[vmassol]

@mleduc

+1 for that option, until somebody requests this again with a use case.

The use cases are quite obvious and they’re valid IMO. They’re listed in Loading... (consistency between location of TOCs in pages, not having to manually add a TOC macro on all pages).

The question I was asking was more whether we want to provide this feature or not by default in XS. Because each feature has a cost: implementation, documentation, maintenance, more complex software and thus reduced usability. For me the cons outweight the pros, to have it in XWiki/XS.

Said differently, this thread is about adding an ADR to decide that we don’t want to implement Auto TOC (ofc we can always change our mind in the future by creating a superseding ADR ;)).

Then when someone asks for it, we can point to this thread or the ADR (if we record it). Ofc anyone could implement it as a contrib extension, the ADR is just about having it in XWiki.

[CharpentierLucas]

In my opinion an implementation with a Panel would have fairly low maintenance cost given that we already bundle the ToC macro AND a bunch of panels (most of which are less useful than a prospective ToC panel IMO). From what I know, maintenance cost of a panel is not that high.

This one should be pretty simple to do, and panels come with the advantage of:

• toggable by the admin
• consistent place in the DOM
• customizable “easily” by admins (ease is relative, but I think it’s more straightforward than if we implement it with a rendering transformation)
• Leaves space for the content of the page, easy for users to dismiss/overlook the content of the ToC if they don’t need it.

I can take responsibility of proposing this new panel in the next roadmap if we decide it’s worth it .

---

1. No opinion on my part, I’m not sure what part of the user base would use the ToC if it was included by default on every page (probably would depend on the design we use too )
2. No. I think it’s a too high level of abstraction for it to make sense in xwiki-rendering. At least heading numbering has an impact at the level of the heading itself. IMO the ToC is not content and handling it does not fall under the responsibility of xwiki-rendering.
3. No, those items are not documents so I don’t think they should be inside the document tree. (however an improvement to use an xwiki tree to display the ToC could be something, no strong opinion about it though)
4. IMO it’s one of the best options (see above)
5. I think we could achieve a very similar user experience with lower costs and tech debt by using a panel.

Thanks for bringing this discussion forward!
Lucas C.

[MichaelHamann]

Coming from DokuWiki, I like how it automatically displays a table of contents. The table of contents is not always present but only if there are at least a configurable number of headings in the page, by default this is 3.

Doing this as part of a transformation would have the advantage that it would be quite easy to also check if there is already a TOC in the page, and if yes, omit it. With the panel the problem is that you’ll have an additional TOC if there was already one in the page. Further, with the panel there is another problem: you’ll need to re-execute the macro transformations on the page to get a correct TOC. If the page contains any scripts that perform an action based on some URL parameter, this could be dangerous as the action would be performed twice.

So from my side:

1. +1, I think having a TOC automatically is nice.
2. +1, with global configuration options similar to DokuWiki, with overrides on the space/page level.
3. -0, I think this would clutter the tree too much. However, +1 to provide pickers for headings, e.g., for selecting a section in a link anchor or an include macro.
4. -0, I’m not totally against providing such a panel, but I think it could have important problems (see above).
5. -0, this has the same problems as the panel regarding executing transformations again.