Rendering Module

The XWiki Rendering Module provides the API to convert textual input content in a given syntax into an output content in another syntax. 


The XWiki Rendering Architecture can be summarized by the image below:


The Parser parses a text input like "xwiki/2.0" syntax or HTML and generates an XDOM object. This object is an Abstract Syntax Tree which represents the input into structured blocks. For the list of supported syntaxes, check the below section.

The Renderer takes an XDOM as input and generates an output like "xwiki/2.0" syntax, XHTML or PDF. 

The Transformation takes an XDOM as input and generates a modified one. The available Transformations are:

XWiki Rendering supports 2 cases: working or not inside a wiki. If you are not inside a wiki, the Link and Image Renderers will only handle links and images pointing to URLs and won't handle them if they point to a document. In order to know whether it is inside a wiki or not, the code checks to see if it can find a component implementing the WikiModel interface.

The Macro Transformation searches for all macro blocks inside the XDOM object and replaces them with blocks generated by various macros. For each macro block found, the Macro Transformation verifies whether there is a corresponding macro registered for it and for the target syntax. Macros can be registered for all syntaxes or only for a given syntax. Finally, macros are sorted by priority and executed one by one by replacing the macro block with the list of blocks generated by the macro. The process is repeated until there are no more macro blocks left in the XDOM.

The Macro Transformation uses a MacroTransformationContext which augments the TransformationContext by holding additional information such as the current XDOM block being processed or whether the macro is called inline or not. 

Starting with XWiki 6.0, it is possible to access the context of the rendering in progress from any components. The information, initially provided by the org.xwiki.rendering.transformation.TransformationContext and org.xwiki.rendering.transformation.MacroTransformationContext are now available to any component using the RenderingContext role. For this context to be properly actuated, any process that initiate a transformation without using the default implementation of TransformationManager role (or implement it) should take care of it.

For the full list of Java Rendering macros, go to this page.

Supported Syntaxes

Name Id Input Syntax (there is a Parser for parsing this syntax into an XDOM object) Output Syntax (there is a Renderer for rendering an XDOM into this syntax)
XWiki 2.1xwiki/2.1YesYes
XWiki 2.0xwiki/2.0YesYes
XWiki 1.0xwiki/1.0YesNo
XHTML 1.0xhtml/1.0YesYes
HTML 4.01html/4.01YesYes
HTML 5.0html/5.0YesYes
Plain Textplain/1.0YesYes
DocBook 4.4docbook/4.4YesYes
XDOM XML Currentxdom+xml/curentYesYes
XDOM XML 1.0xdom+xml/1.0YesYes
Confluence XHTMLconfluence+xhtml/1.0YesNo
Markdown 1.0markdown/1.0YesNo
Markdown 1.1apt/1.0YesYes

Required JARs

XWiki Rendering requires several JARs in the JAVA Classpath:

Finally, you will need all the transitive dependencies required by the aforementioned JARs. The easiest way is to use Maven as explained in the next section.

The latest XWiki Rendering API Javadoc is available here.

Use Maven to Build Dependencies

Below there is an example of a "pom.xml" file with a dependency on xwiki-rendering-transformation-macro for using the Table of Contents Macro and the HTML Macro.

<project xmlns="" xmlns:xsi="" xsi:schemaLocation="">
  <!-- Logging with Logback -->

Parser Strategies

For the moment we support 4 parser strategies:

  • Parsing code can be implemented directly in the XWiki Rendering syntax module. For the moment, there aren't any syntaxes using this strategy.


The XWiki renderers implement the Renderer interface. The existing implementations include:

Link and Image Types

When using the XWiki Syntax 2.1, it is possible to extend the generic link syntax [[label>>referenceType:referencePath]] by adding a new referenceType. The process has 2 steps:

  • Implement a component with the ResourceReferenceTypeParser role which is used to convert from a String to a ResourceReference. The existing type implementations are available here.
  • Implement a component with the XHTMLLinkTypeRenderer role which is used when rendering a link into XHTML. The existing link type implementation are available here.

In a similar way, it is possible to extend the generic image syntax [[image:referenceType:referencePath]] by adding a new referenceType. The process also has 2 steps:

XWiki Rendering Script Service

The XWiki RenderingScriptService class provides Rendering-specific scripting APIs:

  • public List<Syntax> getAvailableParserSyntaxes(){} - returns the list of syntaxes for which a Parser is available
  • public List<Syntax> getAvailableRendererSyntaxes(){} - returns the list of syntaxes for which a Renderer is available
  • public List<String> getDefaultTransformationNames(){} - returns the names of Transformations that are configured in the Rendering Configuration and which are used by the Transformation Manager when running all transformations
  • public XDOM parse(String text, String syntaxId){} - parses a text written in the passed syntax
  • public String render(Block block, String outputSyntaxId){} - renders a list of Blocks into the passed syntax
  • public Syntax resolveSyntax(String syntaxId){} - converts a Syntax specified as a String into a proper Syntax object

To expose the Rendering module API in Velocity use the syntax: $services.rendering.*.


1. Parse a HTML content and render it in "xwiki/2.1" syntax:

#set ($xdom = $services.rendering.parse(" <table>
</table> "
, "xhtml/1.0"))
#set ($xwikiSyntax = $services.rendering.render($xdom, "xwiki/2.1"))

will display 


2. Display the list of syntaxes for which a Parser is available:


More examples like how to execute macros or how to convert an input from one syntax to another are available here.

3. Add a new transformation.

Bonus: see a related blog post on how pages are rendered with XWiki syntax to format text, create tables, create links, display images, etc.

Search this space