PegDown Markdown module Play!

This is a module for the Play! framework which adds Markdown formatting support using the pegdown library.

Usage

There are currently two ways to use this module, as a tag and as an extension.

#{markdown}
    This content will be converted to Markdown.
#{/markdown}

${"this content will be converted to Markdown".markdown()}

Whitespace trimming and preservation

In the case of the tag, by default it will try to strip any leading whitespace caused by indentation; if this trimming causes you issue, you can pass the preserveWhitespace:true option to the tag to disable it.

#{markdown}
    This content will be dedented.
#{/markdown}

Would be treated as if it were written like:

#{markdown}
This content will be dedented.
#{/markdown}

To disable this behaviour, you’d write:

#{markdown preserveWhitespace:true}
    This content will be dedented.
#{/markdown}

Inline mode

If you only need to output a single paragraph of text and would rather markdown didn’t produce the paragraph tag for you, then you can use the inline:true switch or the markdownInline extension.

#{markdown inline:true}
    This text won't produce a paragraph tag.
#{/markdown}

${"This text won't produce a paragraph tag.".markdownInline()}

Configuration

For basic use, simply add the module to your dependencies.yml; for use of the pegdown extensions refer to the configuration options below.

The available extensions can be seen in the pegdown readme. All extensions are listed below with the equivalent setting for your config. To enable any extension, add the appropriate setting to your application.conf and set it to true.

For example: pegdown.autolinks=true

Available options

• pegdown.abbreviations — Abbreviations in the way of PHP Markdown Extra.
• pegdown.all — Enable all extensions.
• pegdown.autolinks — Plain (undelimited) autolinks the way Github-flavoured-Markdown implements them.
• pegdown.definitions — Definition lists in the way of PHP Markdown Extra.
• pegdown.fencedCodeBlocks — Fenced Code Blocks in the way of PHP Markdown Extra or Github-flavoured-Markdown.
• pegdown.hardwraps — Alternative handling of newlines, see Github-flavoured-Markdown.
• pegdown.none — Disable all extensions.
• pegdown.qoutes — Beautifies single quotes, double quotes and double angle quotes.
• pegdown.smarts — Beautifies apostrophes, ellipses and dashes.
• pegdown.smartypants — Convenience extension for enabling both pegdown.smarts and pegdown.quotes at once, like SmartyPants.
• pegdown.suppressAllHtml — Suppresses the output of all HTML elements.
• pegdown.suppressHtmlBlocks — Suppresses the output of HTML block-level elements.
• pegdown.suppressInlineHtml — Suppresses the output of inline HTML elements.
• pegdown.tables — Tables similar to MultiMarkdown.
• pegdown.wikilinks — Support [[Wiki-style links]].

Inline extensions

Extensions can be enabled/disabled on a per-use basis too when you’re using the tag syntax; simply pass the extension name to the tag with true or false to enable or disable it.

For example, to disable all HTML in a particular markdown block:

#{markdown suppressAllHtml:true}
    <p>This won't be processed.</p>
    But this will.
#{/markdown}

Alternatives/Why use this module?

There’s another markdown module for the Play! framework; however, it’s only an implementation of the pure Markdown definition. For anyone who wants any of the extensions from Github-flavoured-Markdown, PHP Markdown Extra, or SmartyPants, then this is the module for you; otherwise, there’s nothing else different between the two (although the other module claims to have better performance due to its underlying library).

In short, it boils down to this: the markdown module is based on markdownPapers and this module is based on pegdown.

Credits

• Markdown — John Gruber
• SmartyPants — John Gruber
• pegdown — Mathias
• play-pegdown — James Gregory

Bugs etc…

Bugs should be raised on the Github Issues list and you can find the code and fork it in the Github project.

History

• 0.1 — First version, nothing fancy.