Auto TOC in XWiki?

Development
#1

Hi devs,

Back in 2014 I had implemented an autotoc rendering transformation to automatically add a {{toc/}} macro at the top of wiki pages. See https://jira.xwiki.org/browse/XRENDERING-345 and https://github.com/xwiki/xwiki-rendering/commit/a5bf220fbb347f91dbbccb47f5b6e7eb721fa3ff

We have several options:

  1. make it a contrib extension
  2. bundle it in xwiki-rendering, as we do for the wikiword, linkchecker and icon transformations
  3. consider it’s not a good idea and drop it.
    3.1 Provide a TOC panel, see https://jira.xwiki.org/browse/XWIKI-13750 (which isn’t implemented FTM).
    3.2 Provide another mechanism, like an “after title” UIX to display it and which could be folded/unfolded, possibly with a cookie to remember the folding state.
    3.3 Provide sections as an addition tree node level in the Document Tree macro and thus in the Navigation Panel.

Since this is a FAQ (having an auto toc), my preference would be to add a solution for it in XWiki by default (i.e. not 1)).

Re 1) and 2), I also think that we need some config mechanism so that it’s only executed in some page hierarchies, as otherwise it would get executed for all pages, leading to possibly sub-optimal results on some pages. We could imagine some xwiki.properties configuration using regexes (similar to the renderingcache).

Re 1) and 2), we might also need a config option in xwiki.properties to decide if the added toc is floating or not.

So WDYT about the different options?

My preference:

  • Immediately, I’d go for 2) since it’s mostly ready and since it’d be off by default, it cannot harm much.
  • For the further future, I’m not sure, 3.1 is nice but it takes a lot of visual space (too much IMO) and forces to have panels displayed. 3.2, if done right, feels interesting. 3.3 seems appealing too.

Thanks
-Vincent

1 Like
Auto TOC in XWiki (second try)
#2

3. is maybe a bit harsh

My preference goes to 1. right now, since in its current state (without a default behavior making sure it’s executed only for simple wiki page content transformation) it’s not usable (it does not even check if there is already a toc).

#3

Yes but my idea was to quickly add the config options I mentioned which would not take more time than creating the new contrib extension.

#4

I don’t think the main problem really is configuration unless your plan is to have a white list of pages in that configuration and the macro would not do anything by default.

#5

Yes it’s a whitelist, same as the rendering cache (and nothing by default).

#6

Asked again in Auto TOC in XWiki (second try)