Markdown support in JSPWiki#
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.)
- Almost all plugins (more on this below)
- Inline images
- 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