README.textile

December 7, 2011 · View on GitHub

h1. PegDown Markdown module Play!

This is a module for the Play! framework which adds "Markdown":http://daringfireball.net/projects/markdown/ formatting support using the "pegdown":https://github.com/sirthias/pegdown library.

h2. 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()}

h3. 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}

h3. 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()}

h2. Configuration

For basic use, simply add the module to your @dependencies.yml@; for use of the "pegdown extensions":https://github.com/sirthias/pegdown/blob/master/README.markdown refer to the configuration options below.

The available extensions can be seen in the "pegdown readme":https://github.com/sirthias/pegdown/blob/master/README.markdown. 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@

h3. 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]]@.

h3. 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}
    This won't be processed.
    But this will.
#{/markdown}

h2. 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.

h2. Credits

h2. Bugs etc...

Bugs should be raised on the "Github Issues list":https://github.com/jagregory/play-pegdown/issues and you can find the code and fork it in the "Github project":https://github.com/jagregory/play-pegdown.

h2. History

0.1 -- First version, nothing fancy.