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).
`$markdown.blockToMarkdown()`	Converts a Block Editor JSON object to Markdown.

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.

Convert a Block Editor Field to Markdown#

The blockToMarkdown method converts a Block Editor JSON object to Markdown. It supports two output flavors.

Usage#

$markdown.blockToMarkdown(json)
$markdown.blockToMarkdown(json, flavor)

Parameters#

Parameter	Default	Description
`json`	Required	A Block Editor field object (e.g. `$dotcontent.find("$inode").fieldName`).
`flavor`	`"readable"`	Output flavor: `"readable"` (default) or `"roundtrip"`.

Output Flavors#

Flavor	Description
`"readable"`	Human-readable Markdown. Rich blocks (embedded contentlets, YouTube embeds, etc.) flatten to descriptive plain text. Use for display, AI indexing, or anywhere the Markdown will not be written back to dotCMS.
`"roundtrip"`	Lossless Markdown. Rich blocks are emitted as `dotcms-*` fenced code blocks (e.g. `dotcms-content`, `dotcms-youtube`). Use when you intend to edit the Markdown and write it back via the workflow fire API.

Examples#

Human-readable output (default):

$markdown.blockToMarkdown($dotcontent.find("$inode").blogContent)

Round-trip output (for editing and writing back):

$markdown.blockToMarkdown($dotcontent.find("$inode").blogContent, "roundtrip")

The field's own .toMarkdown() shorthand is equivalent:

$dotcontent.find("$inode").blogContent.toMarkdown()
$dotcontent.find("$inode").blogContent.toMarkdown("roundtrip")

$dotcontent.find() accepts an inode, not an identifier. Pass the inode when calling either form.

For a full description of the dotcms-* fence vocabulary used in roundtrip output, see Block Editor: The dotcms-* Vocabulary for Rich Blocks.

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>