Numbered Reference Macro

Last modified by Manuel Leduc on 2022/11/28 00:04

cogProvides numbered headings, figures and tables and references to them
Developed by

Vincent Massol

Active Installs82
1 Votes
LicenseGNU Lesser General Public License 2.1

Since v1.2 requires XWiki 10.2RC1+

Installable with the Extension Manager


Provides numbered headings, figures and tables. Also allows to create reference links to those numbered elements.

This extension and Reference Macro both define a reference macro and should not be installed in the same wiki.
Note that Reference Macro is now replacing this extension and thus should be used instead. Reference Macro is part of Numbered Content which provides numbering and reference for wiki contents.

Numbered Headings

Example usage:

See section {{reference section="D"/}}. Invalid {{reference section="invalid"/}}.

= heading A =

= heading B =

{{include reference="NumberedHeadings.Test.WebHome"/}}

== heading C ==

== {{id name="D"/}}heading D ==

=== heading E ===

= heading F =

Generates the following when viewing the page:


Avoiding Numbering

XWiki 1.4+

It's possible to avoid numbering of a specific heading by setting the data-xwiki-rendering-protected parameter on the heading block (or on a wrapping group block). For example:

(% data-xwiki-rendering-protected='true' %)
= heading A =


(% data-xwiki-rendering-protected = 'true' %)(((
= heading A =

Numbered Figures & Tables

Example usage:

See figure {{reference figure="f1"/}}.


{{figureCaption}}{{id name="f1"/}}An image{{/figureCaption}}

See table {{reference figure="t1"/}}.


{{figureCaption}}{{id name="t1"/}}A table{{/figureCaption}}

Generates the following when viewing the page (with this CSS used):



The Numbered Figure transformation generate some labels which can be internationalized. The following translation keys are used:

  • transformation.numberedReferences.figurePrefix
  • transformation.numberedReferences.tablePrefix

Default English translations:

transformation.numberedReferences.figurePrefix = Figure {0}:
transformation.numberedReferences.tablePrefix = Table {0}:


  • When using the {{reference}} macro to reference a heading, the section value must point to either an auto-generated heading anchor or the name parameter of an {{id}} macro located inside the heading.
  • When using the {{reference}} macro to reference a figure or table, the figure and table values must point to the name parameter of an {{id}} macro located inside the {{figureCaption}} macro.
  • The elements are numbered thanks to several Rendering Transformations and at the moment of writing, Transformations are global. Thus if you activate this transformation on your wiki, you'll get numbered elements for all pages of your wiki and subwikis.

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

This extension contributes two Transformations which need to be activated. This is done by editing your file and making sure you have a  rendering.transformations property with the numberedheadings id in the list for the heading numbering feature and the numberedfigures id for the figure/table numbering feature. For example:

rendering.transformations = macro, icon, numberedheadings, numberedfigures

Release Notes












Dependencies for this extension (org.xwiki.contrib:macro-numbered-references 1.4):

Get Connected