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>