CommonMark Markdown 1.2 Syntax Parser and Renderer

Description

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.

Details

The Markdown flavor used is CommonMark 0.28.

Note that a GitHub-Flavored Markdown syntax is also available at GitHub Flavored Markdown Syntax.

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.
  • Example 1: ![[alt|image:[email protected]]]
  • Example 1: ![[alt|[email protected]]] (image: prefix is optional and the default)

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).

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.

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".

Dependencies

Dependencies for this extension (org.xwiki.contrib.markdown:syntax-markdown-commonmark12 8.9):

• com.vladsch.flexmark:flexmark 0.64.8
• com.vladsch.flexmark:flexmark-ext-wikilink 0.64.8
• com.vladsch.flexmark:flexmark-ext-autolink 0.64.8
• com.vladsch.flexmark:flexmark-ext-definition 0.64.8
• com.vladsch.flexmark:flexmark-ext-tables 0.64.8
• com.vladsch.flexmark:flexmark-ext-gfm-strikethrough 0.64.8
• com.vladsch.flexmark:flexmark-ext-abbreviation 0.64.8
• com.vladsch.flexmark:flexmark-ext-superscript 0.64.8
• com.vladsch.flexmark:flexmark-ext-xwiki-macros 0.64.8
• org.xwiki.rendering:xwiki-rendering-api 12.10
• org.xwiki.rendering:xwiki-rendering-syntax-plain 12.10
• org.xwiki.rendering:xwiki-rendering-syntax-xwiki21 12.10