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
A complete example showing the integration of the markdown parser/renderer can be found at this github repo

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