Deprecated the numbered property of the Table of Content macro

Hello all,

The Table of Content (ToC) macro has a numbered boolean property.
When this property is set to true, each item is prefixed by a number (i.e., <ol> is used instead of <ul>).

Now that the numbered content extension exists, this way of numbering ToC items is deprecated:

  • the headings themselves are not numbered
  • sub-levels are not prefixed by the level of their parents
  • no possibility to skip the numbering for a given heading

I propose to:

  • deprecate the numbered property and move it to legacy in XS.
  • hide it in numbered content app and ignore its value, until we move to a parent version where it has been deprecated (meaning that all ToC macro would be considered as numbered=false as soon as the extension is installed)
  • document the number content app to explain how to reactivate numbering (possibly with a snippet showing how to list the impacted pages).


+1 to say that we don’t support the UC of numbering the TOC but not the headings. If the community wants the feature, it could be added as a contrib extension overriding the TOC macro. It could also be added in the content numbering app by offering a {{nonumber}} macro to prevent numbering part of the markup (more generic need).




I don’t really like the change to the behavior of existing uses of the TOC macro as this is an effective API breakage (not in the technical sense but from the overall macro API point of view)/feature removal which is - from my understanding - something we promise not to do without a good reason and I cannot see a good reason for this. Further, there will be no way to restore the previous behavior (not even by installing a contrib extension). I’m +1 for ignoring the parameter when headings are numbered (to avoid duplicate numbering) and I’m +1 for moving the parameter to some advanced section or even hiding it from the UI. However, I’m -0 for modifying the output of the macro in documents without numbered headings.

I agree this is a breakage, and the reason is that the feature was never really useful and has a better replacement now. Which, imo is a good enough reason.

As @vmassol said, we could introduce the feature back by extension if it was to be requested.

+0 for making it advanced
-1 to fully hide it if it can be taken into account as otherwise users have to rely on wiki editing to update the parameter if is already defined.

The numbered property is now marked as advanced and is not proposed to users unless they expand the “more” section of the toc macro edition modal.
See XRENDERING-719: Make the numbered property advanced (#263) · xwiki/xwiki-rendering@90f2a53 · GitHub