CFX_Markdown

CFX_Markdown is a ColdFusion CFX tag written in Java; an implementation of the Markdown text-to-HTML processor.

It is based on MarkdownJ, the excellent Java port of Markdown written by Pete Bevin.

After more than a year of hoping someone would port Markdown to ColdFusion, I realised that Pete had already done most of the work by doing the Java port; it was then just a case of adapting MarkdownJ as a CFX tag – a simple enough task that I managed it with no previous experience of Java!

As of version 0.3.0, CFX_Markdown also includes SmartType, which converts characters into their proper typographical equivalents – e.g. smart quotes, ellipsis entities.

What is Markdown?

Markdown is a text-to-HTML conversion tool for web writers, originally written by John Gruber. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

You can view an example of Markdown code – this is the body of this page as defined using Markdown.

To learn more about Markdown, including a detailed guide to the syntax, please visit the Markdown page at John’s site, Daring Fireball.

How to use CFX_Markdown

Once you have installed CFX_Markdown on your server (installation instructions are provided with the download), you can call it from any ColdFusion template.

The syntax is very simple. In its simplest form, it takes a single argument – textin – which contains the text to be formatted:

<cfx_markdown
	textin="Some _Markdown_ text to format">

This can also be in the form of a ColdFusion variable, e.g.:

<cfx_markdown
	textin="#rawText#">

This will return the (X)HTML-formatted content to the page in place of the tag.

CFX_Markdown takes three additional, optional arguments. If variable is specified, then the formatted (X)HTML will be assigned to that variable, rather than written directly to the page. For example:

<cfx_markdown
	textin="Some _Markdown_ text to format"
	variable="myVar">

This will create a variable, myVar, containing the tag’s output.

The second argument is output. By default, CFX_Markdown returns XHTML; but if you specify output="html4", then the resulting code will be in HTML 4 format:

<cfx_markdown
	textin="Some _Markdown_ text to format"
	output="html4">

The final argument, smarttype, invokes the SmartType processor. This can take a variety of arguments – either a combination of letters, or the keywords all or stupefy.

q — process smart quotes and apostrophes
d — convert single dashes to en-dashes, double hyphens to em-dashes
e — convert three or four dots into ellipses
x — convert x surrounded by digits into multiplication sign
w — removes MS Word-generated smart quotes, etc.
all — equivalent to qdexw
stupefy — converts all SmartType entities back to ASCII equivalents

For example:

<cfx_markdown
	textin="Some 'Markdown' text -- now with SmartType..."
	smarttype="qdexw">

…would produce the HTML:

<p>Some &#8216;Markdown&#8217; text &#8212; now
	with SmartType&#8230;</p>

If you would like a character to be ignored by SmartType, it can be escaped by preceding it with a backslash, e.g.:

He was 6\'4\" tall.

All HTML tags are exempt from the conversion, as are HTML comment blocks. Also, all text inside a few specific block-level HTML elements (pre, code, kbd, script, math) is ignored.