Markdown Syntax 1.2

Last modified by Vincent Massol on 2020/06/29 00:20

text_kerningMarkdown 1.2 Syntax Parser and Renderer
Developed by

Vincent Massol, XWiki Development Team

Active Installs849
0 Votes
LicenseGNU Lesser General Public License 2.1

Installable with the Extension Manager


This version of Markdown for XWiki is built on Flexmark Java which is greatly improved over Pegdown which was used for Markdown Syntax 1.0 and Markdown Syntax 1.1.



The Markdown flavor used is CommonMark 0.28.

Link Syntax

There are 2 link syntaxes supported:

  • [...](...): This is the original Markdown syntax and it should be used for URLs and mailto URIs.
  • [[...]]: This is the wikilink extension and should be used for links to other pages in the wiki. More precisely the exact syntax is [[label|reference|parameters]] where label and parameters are optional. In addition the reference format is the same as for the XWiki Syntax 2.1.
    • Example 1: [[label|Page1.Page2]]. Link to the page having the Page1.Page2 reference.
    • Example 2: [[label|Page1.Page2|queryString="a=b&c=d" anchor="anchor"]]. Link that specifies a query string and an anchor

Image Syntax

There are 2 image syntaxes supported:

  • ![...](...): This is the original Markdown syntax and it should be used for image URLs.
  • ![[...]]: This is the wikiimage extension and should be used for images located on other pages in the wiki. More precisely the exact syntax is ![[label|reference]] where label is optional. In addition the reference format is the same as for the XWiki Syntax 2.1.

Macro Syntax

Since XWiki supports macros we have augmented the Markdown syntax with support for macro. The following syntaxes are supported:

  • {{<macroname>/}}: this is a macro without parameter and without content (e.g. {{toc/}})
  • {{<macroname> <param>="<value>".../}}: this is a macro with parameters but no content
  • {{<macroname> <param>="<value>"...}}<content>{{/<macroname>}}: this is a macro with parameters and content. Note that the content can on several lines.

All the macros available in the XWiki Syntax are also available in markdown.

Differences with markdown/1.1

  • In markdown/1.1, the [...](...) syntax for links was used for all types of links including links to wiki pages but it caused problems since whitespaces were not supported for example.
  • Strikethrough syntax is supported with ~foo~.
  • Wiki image syntax were not supported in markdown/1.1.
  • Spaces in superscript/subscript were not supported without having to escape them in markdown/1.1.
  • Newline in HTML tags are valid and supported in markdown/1.2 (contrary to markdown/1.1).
  • Spaces in tables are not significant in markdown/1.2 (contrary to markdown/1.1).
  • In markdown/1.1 there was a special syntax for inline macros which is no longer the case in  markdown/1.2 (there's now a single syntax).

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). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

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.

Note that installing this version also installs Markdown Syntax 1.0 and Markdown Syntax 1.1.

The installation depends on the version of XWiki you have:

  • XWiki >= 8.2M2: Nothing special, works fine without any manual setup.
  • XWiki == 8.2M1: If you're installing on Jetty, you need to replace the jython-standalone-2.7.0-xwiki-2.jar JAR in WEB-INF/lib by this one
  • XWiki < 8.2M1, XWiki < 8.1 or XWiki < 7.4.4:
    • You need to remove the existing XWiki Markdown JARs that were bundled at that time (and which have been removed in XWiki 8.2M1). To do so remove the following 2 JARs: WEB-INF/lib/xwiki-rendering-syntax-markdown10-<version>.jar and WEB-INF/lib/xwiki-rendering-syntax-markdown11-<version>.jar.
  • You'll need to install the extension JAR (and its dependencies) manually in WEB-INF/lib (i.e. as a core extension). This is caused by the following bug that was fixed in XWiki 7.4.4, 8.1 and 8.2M1.

Also note that when installed with the Extension Manager, the extension needs to be installed "on Farm".

Release Notes


  • Closed MARKDOWN-65 Inline code syntax produce a red rectangle around some content on XWiki 2.2
  • Closed MARKDOWN-64 Remove markdown/1.0 and markdown/1.1
  • Closed MARKDOWN-62 Upgrade to Flexmark-Java 0.50.44


  • Closed MARKDOWN-49 Lists are disappearing when in XWiki 10.0 till 10.11.11/11.3.7/11.10.2/12.0



  • Closed MARKDOWN-51 Wiki links with "." are not escaped correctly


  • Closed MARKDOWN-47 Header row separator must have at least 3 dashes when rendering tables
  • Closed MARKDOWN-46 Invalid rendering when table has no header cells
  • Closed MARKDOWN-44 Failure to render macros with parameters on XWiki version 8.2+
  • Closed MARKDOWN-43 Be able to install Markdown 1.2 syntax without installing Markdown 1.0 & 1.1 syntaxes
  • Closed MARKDOWN-42 Be able to install Markdown 1.1 syntax without installing Markdown 1.0 syntax


  • Closed MARKDOWN-41 Standalone Code macro is not rendered properly in Markdown syntax
  • Closed MARKDOWN-37 Upgrade to flexmark-java 0.27.0


  • Closed MARKDOWN-36 2 spaces at end of line are not transformed into a newline




  • Closed MARKDOWN-32 Link renderer should generate an autolink syntax when no label is found and for URLs and email addresses
  • Closed MARKDOWN-31 Only support URLs and email addresses in autolinks and [...](...) links
  • Closed MARKDOWN-30 Add support for query string + anchors for wiki links
  • Closed MARKDOWN-29 Spaces in tables should not be significant
  • Closed MARKDOWN-27 Add support for wiki images
  • Closed MARKDOWN-26 Add support for labels in wiki links
  • Closed MARKDOWN-23 Consider that newlines in HTML tags are valid HTML
  • Closed MARKDOWN-22 Allow spaces in superscript/subscript without having to escape them
  • Closed MARKDOWN-21 Add support for strikethrough
  • Closed MARKDOWN-20 Allow to configure the markdown extensions used for the parser
  • Closed MARKDOWN-19 Ability to configure the Markdown parser family to use
  • Closed MARKDOWN-18 Implement Common Mark 0.27
  • Closed MARKDOWN-16 Move to flexmark-java
  • Closed MARKDOWN-12 Don't fail with an NPE when there are spaces in an image reference


Dependencies for this extension (org.xwiki.contrib.markdown:syntax-markdown-markdown12 8.6):

  • com.vladsch.flexmark:flexmark 0.50.44
  • com.vladsch.flexmark:flexmark-ext-wikilink 0.50.44
  • com.vladsch.flexmark:flexmark-ext-autolink 0.50.44
  • com.vladsch.flexmark:flexmark-ext-definition 0.50.44
  • com.vladsch.flexmark:flexmark-ext-tables 0.50.44
  • com.vladsch.flexmark:flexmark-ext-gfm-strikethrough 0.50.44
  • com.vladsch.flexmark:flexmark-ext-abbreviation 0.50.44
  • com.vladsch.flexmark:flexmark-ext-superscript 0.50.44
  • com.vladsch.flexmark:flexmark-ext-xwiki-macros 0.50.44
  • org.xwiki.rendering:xwiki-rendering-api 8.3
  • org.xwiki.rendering:xwiki-rendering-syntax-plain 8.3
  • org.xwiki.rendering:xwiki-rendering-syntax-xwiki21 8.3
Created by Vincent Massol on 2016/05/22 14:45

Get Connected