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 &#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.



### Download

[Download CFX_Markdown and example files][download] [48 KB]

[Download the CFX_Markdown source][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.



   [markdown]:         http://daringfireball.net/projects/markdown/
   [markdownj]:        http://sourceforge.net/projects/markdownj/
   [daring fireball]:  http://daringfireball.net/
   [raw text]:         /CFX_Markdown/cfx_markdown.txt
   [download]:         /CFX_Markdown/CFX_Markdown-0.3.0.zip
   [source]:           /CFX_Markdown/CFX_Markdown-source-0.3.0.zip