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 / editors#

As of JSPWiki 2.11, there is built in (some) support for using Markdown instead of normal JSPWiki syntax.

The following line should be added to your jspwiki-custom.properties file:

jspwiki.syntax=markdown

which is equivalent to adding the following lines 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.syntax.decorator=org.apache.wiki.htmltowiki.syntax.markdown.MarkdownSyntaxDecorator
jspwiki.syntax.plain=plain/wiki-snips-markdown.js

A complete example showing the integration of the markdown parser/renderer can be found at this github repo

Features#

• Attributes extension
• Definition extension
• Tables and TOC extension extensions
• A custom JSPWiki extension, that currently supports:
  • 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#

• Initial set of WikiPages for markdown / markup migration tool?
• Plugins implementing HeadingListener (f.ex., TableOfContents*) are not supported
  • HeadingListener 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.
  • To overcome this limitation in the case of TableOfContents plugin, it 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

Category.Documentation