Markdown support in JSPWiki#

Markdown behavior#

It is possible to render Markdown text on your wikipages through Markdown Behavior, a javascript extension which allows to render pages written in markdown, while still using standard JSPWiki syntax.

Markdown parser / renderer#

Beginning with JSPWiki 2.10.3-git-44 there is also (some) support for using Markdown instead of normal JSPWiki syntax.

This markdown support is not directly built in yet though, as it requires at least Java 7 to run, whereas JSPWiki 2.10 requires at least Java 6, so the jspwiki-markdown jar must be manually included inside the main JSPWiki war (f.ex., through a Maven depependency). Once that is done, the following lines should be added to your jspwiki-custom.properties file:

jspwiki.renderingManager.markupParser=org.apache.wiki.parser.markdown.MarkdownParser
jspwiki.renderingManager.renderer=org.apache.wiki.render.markdown.MarkdownRenderer
jspwiki.renderingManager.renderer.wysiwyg=org.apache.wiki.render.markdown.MarkdownRenderer

JSPWiki 2.11 will most probably require Java 8, so this markdown support will be built in.

Features#

The Parser/Renderer is based on Flexmark + a custom JSPWiki extension. Currently it supports:

• CommonMark flavour of Markdown
• Wiki links (internal, external, interwiki, edit, etc.)
• Variables
• Almost all plugins (more on this below)
• Inline images
• Footnotes
• ACLs
• Metadata
• WYSIWYG edition

Gotchas / Current shortcomings#

• Plain editor toolbar support
• Initial set of WikiPages for markdown / markup migration tool?
• %%css constructs. A new extension for this should be made, there is no support for this.
• Plugins implementing HeadingListener (that is, TableOfContents) are not supported
  • this interface is fired by JSPWikiMarkupParser every time it finds a header (more precisely, for every heading, JSPWikiMarkupParser generates a "#" link with the section reference and then registers a HeadingListener).
  • The way flexmarks parses and renders markdown, doesn't allow to generate the TOC this way.
  • Right now, TableOfContents plugin is translated to flexmark's own TOC extension, surrounded with some divs.
  • There are two proper ways of adding support for this:
    • add enough css so that both html render more or less the same. Parameters parsing should be implemented anyways.
    • add a new Flexmark extension for TOC, probably forking+adapting the existing TOC extension.
• Thorough end-to-end testing