CFX_Markdown
What is 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).
The body of this page is written in Markdown and processed using CFX_Markdown; you can view the raw text as an example.
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 ‘Markdown’ text — now with SmartType…</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.
Download
Download CFX_Markdown and example files [48 KB]
Download the CFX_Markdown source [1 KB]
Requirements
CFX_Markdown has been tested in ColdFusion MX 7; but it should work in any version of ColdFusion from 4.5 onwards.
You will also need access to the ColdFusion Administrator in order to install CFX_Markdown.