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 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
Features#
The Parser/Renderer is based on Flexmark (CommonMark 0.28 flavour of Markdown) with- 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
- org.apache.wiki.markdown.migration.WikiSyntaxConverter to convert from JSPWiki syntax to markdown
warning
Please note that, as of today, there is no default set of WikiPages for Markdown syntax. You must create them from an initial set of WikiPages for JSPWiki's default syntax, using the WikiSyntaxConverter above .
Gotchas#
- HeadingListener support is not available for plugins implementing it (f.ex., TableOfContents).
- 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 situation, in the case of TableOfContents plugin, it is translated to flexmark's own TOC extension, surrounded with some divs.