Markdown Viewtool

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:

Method	Description
`$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 #

Parameter	Default	Description
`formatted-string`	Required	A Markdown formatted string (using Github markdown format).

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 #

Parameter	Default	Description
`file_name`	Required	The URL of the file to be parsed (on the local dotCMS Site).
`parse_velocity`	false	A 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 following example shows how the Markdown Viewtool is mapped in the toolbox.xml file:


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