Markdown Tool - Documentation topics on: markdown,viewtools,.

Markdown Tool

This dotCMS viewtool provides a github flavored markdown (gfm) compatible markdown parser (for the most part). It is built off of the txtmark project by René Jeschke. It provides a viewtool that can be used in dotCMS to parse text/content for gfm.

Methods

The Markdown viewtool supports the following two methods:

MethodDescription
$markdown.parse()Parses a Markdown formatted string.
$markdown.parseFile()Parses a file containing Markdown formatted text (which may be mixed with Velocity code).

Parse a Markdown-Formatted String

Usage

$markdown.parse(string)

Parameters

ParameterDefaultDescription
formatted-stringRequiredA Markdown (gfm) formatted string.

Example

The following call to the viewtool when iterating over content in velocity:

$markdown.parse(">**Parse** *this* ~~string~~")

produces the following result:

Parse this string

Parse a Field in a Velocity Pull

In a Velocity pull of content, you can use the $markdown.parse tool to iterate over a text field that has both Velocity and Markdown. The Velocity will execute by default, as long as you are looking at your backend page in Live Mode.

Example

#foreach($con in $dotcontent.pull("+contentType:webPageContent)",10,"modDate desc"))
    <h2>$con.title</h2>
    $markdown.parse($content.getRaw("$con.body"))  ##body field Velocity executes, gets the raw field string AND displays text in Markdown format
#end

Parse a File in Markdown Format

You can parse a file that contains Markdown-formatted text using the $markdown.parseFile() method. The parseFile() method supports both pain Markdown files and files which combine both Markdown and Velocity code.

Usage

$markdown.parseFile(file_name)
$markdown.parseFile(file_name, parse_velocity)

Parameters

ParameterDefaultDescription
file_nameRequiredThe URL of the file to be parsed.
parse_velocityfalseA boolean flag specifying whether the contents should be parsed for Velocity as well as Markdown.

Examples

Files Containing Markdown Only

If a file contains only Markdown text (and no Velocity code), you can parse the file using either of the following calling conventions:

$markdown.parseFile("/application/my-file.md")
$markdown.parseFile("/application/my-file.md", false)

Combined Markdown and Velocity

To parse a file that contains both Velocity and Markdown, you must supply a value of true to the parse_velocity parameter:

$markdown.parseFile("/application/my-file.md", true)

Files on a Different Host

To parse a file on a different site (hosted in the same dotCMS instance), include the site name specification when referencing the file:

$markdown.parseFile("//global.host.com/application/my-file.md")

This parses the file /application/my-file.md on the site global.host.com.

Toolbox.xml Configuration

The Markdown Tool is enabled by default in dotCMS. To ensure the Markdown Tool is enabled, verify that the following lines exist in your toolbox.xml file:

<tool>
    <key>markdown</key>
    <scope>request</scope>
    <class>com.dotmarketing.viewtools.MarkdownTool</class>
</tool>

References

For more information on this viewtool, please see the following documentation in the dotCMS Javadocs: