Wiki Syntax#

JSPWiki comes with two wiki syntaxes: JSPWiki and markdown. Also, as with almost everything in JSPWiki, you can add support for your own wiki syntax.

JSPWiki syntax#

The quick list of wiki syntax is available at the Help tab at the top of the page (when you are editing it).

The complete list of the syntax is at TextFormattingRules.

There are also some css/javascript styles at JSPWikiStyle.

Markdown syntax#

Markdown Support is also present in JSPWiki just by enabling jspwiki.syntax=markdown on your jspwiki-custom.properties file.

Adding support for custom wiki syntaxes#

To add support for custom syntaxes you must provide several (groups of) classes / files and add them as normal JSPWiki custom 3rd party code. In this sense, the markdown module on the source distribution is a good example to follow. Specifically you need:

• Wiki syntax markup parser: needed to parse the custom wiki syntax. This is provided by extending org.apache.wiki.parser.MarkupParser (f.ex. org.apache.wiki.parser.markdown.MarkdownParser). This class should be referenced by the jspwiki.renderingManager.markupParser property on the jspwiki-custom.properties file.

• Wiki syntax renderer: needed to output HTML from your custom wiki syntax. This is provided by extending org.apache.wiki.render.WikiRenderer (f.ex. org.apache.wiki.render.markdown.MarkdownRenderer). This class should be referenced by the jspwiki.renderingManager.renderer property on your jspwiki-custom.properties file.

• Wiki syntax renderer fo WYSIWYG editor: needed if you need to display the resulting HTML somewhat different on the WYSIWYG editor, i.e, to add/remove some css classes. Usually you don't need to provide a custom class for this, and it will be fine to use the normal wiki syntax renderer. In any case, you must specify this renderer on your jspwiki-custom.properties file using the property jspwiki.renderingManager.renderer.wysiwyg.

• Support for translating HTML to the custom wiki syntax on the WYSIWYG renderer: by extending extending org.apache.wiki.htmltowiki.syntax.WikiSyntaxDecorator, (f.ex. org.apache.wiki.htmltowiki.syntax.markdown.MarkdownSyntaxDecorator). This class should be referenced by the jspwiki.syntax.decorator property on your jspwiki-custom.properties file.

• A Wiki.Snips.js file: to add support on the plain wiki editor for the custom wiki syntax. This file must end up anywhere inside the META-INF/resources folder of the jar file and referred by the property jspwiki.syntax.plain on your jspwiki-custom.properties file.
  • F.ex., if the file ends up in META-INF/resources/plain/wiki-snips-awesome-syntax.js, it should be referred as jspwiki.syntax.plain=plain/wiki-snips-awesome-syntax.js.
  • The easiest way to provide one of these files is to just copy either the jspwiki syntax snips file or the markdown syntax snips one, and proceed to modify whatever is needed.

• Not really necessary, but you can also provide an EngineLifecycleExtension to enable the custom wiki syntax with one property (ideally jspwiki.syntax), instead of setting 5 low level properties. This will ease the installation and adoption of the custom wiki syntax. See for instance the org.apache.wiki.markdown.MarkdownSetupEngineLifecycleExtension class, which does this for the markdown module.

• Last, but not least, you can also optionally provide a mechanism to migrate existing wiki pages to the new wiki syntax. In the markdown case, this is accomplished through the org.apache.wiki.markdown.migration.WikiSyntaxConverter test file.

Category.Documentation