text_kerningMarkdown 1.1 Syntax Parser and Renderer
TypeJAR
CategorySyntax
Developed by

Vincent Massol, XWiki Development Team

Active Installs0
Rating
Rate!
0 Votes
LicenseGNU Lesser General Public License 2.1

Description

This extension has been broken since XWiki Standard 10.2 and has now been removed. You should use the Markdown Syntax 1.2 instead. Thus, you should migrate your pages written in markdown/1.1 syntax to markdown/1.2.

In order to prevent users from installing it, this extension has been made uninstallable with the Extension Manager. We're still keeping this documentation page for historical reasons for the moment.

This version of Markdown for XWiki builds on top of Markdown Syntax 1.0 but adds supports for XWiki macros, superscript and subscript markup and inline (X)HTML.

markdown-syntaxes.png

Extra Features

Macros

Block Macros

Example:

{{mymacro par1="foo"}}
  content
{{/mymacro}}

Other examples:

  • {{mymacro par1=val1 par2="val 2"}}content{{/mymacro}}
  • {{mymacro}}content{{/mymacro}}
  • {{mymacro par1=val1 /}}
  • {{mymacro /}}

Inline Macros

  • #[mymacro](par1="foo" par2=42 "any content")
    - macro with parameters and content
  • #[mymacro]("any content (quoted)")}} or {{#[mymacro](any content)
    - macro without parameters
  • #[mymacro]
    - macro without parameters and content

Superscript and subscript

This is ^superscript^, but ^this not^, you have to ^escape\ spaces^.
Subscripts are similar, just use ~tilda~ instead. Do you want some H~2~O?

Note that spaces inside superscript and subscript symbols need to be escaped using the \ character.

Inline (X)HTML

Markdown supports an inline HTML so you can write e. g. Hello <del>there</del> and these tags are interpreted as HTML. The problem is that the Pegdown parser is too lenient, it allows any number of whitespaces and even optional new line inside a HTML tag. Therefore it's very hard to properly escape < and > characters to not be confused with a HTML.

We've replaced the parsing rules for an inline HTML in the Pegdown parser with rules for an inline XML. The XML syntax is more strict and so more suitable for an inline (X)HTML in the Markdown syntax. One can still write Hello <del>there</del> and it's parsed as (X)HTML, but something like a < b > c is not. It's more predictable and much simpler to properly escape special characters.

For example, the following is not considered as valid XHTML by the Markdown 1.1 parser:

XHTML is more < strong >strict< /strong> and this is <span
class="red">good</span>

Note that even though the newline after the span is valid XHTML, the Markdown 1.1 parser considers it (wrongly) as invalid and thus is rendered as follows in HTML:

<p>XHTML is more &lt; strong &gt;strict&lt; /strong&gt; and this is &lt;span class="red"&gt;good</span></p>

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.

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 ( 8.5.4):

  • org.xwiki.contrib.markdown:syntax-markdown-markdown11-common 8.5.4
  • org.pegdown:pegdown 1.4.1
  • commons-io:commons-io 2.4
  • org.xwiki.rendering:xwiki-rendering-syntax-xhtml 7.4.5
Tags:
Created by Vincent Massol on 2020/08/17 17:31
    

Get Connected