Saturday, January 8, 2011

Using Markdown in ColdFusion

Markdown is "a text-to-HTML conversion tool for web writers. 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)."

Here's a quick post describing how you can use Markdown in ColdFusion.

First, download MarkdownJ, a Java port of the Markdown conversion utility originally written in Perl. Here's a direct link to the download site: http://code.google.com/p/markdownj/.

Next, either put the markdownj.jar file in the ColdFusion classpath or download JavaLoader. I prefer using JavaLoader, so that's what my example will show.

Finally, some code:


<cfset paths = [ expandPath("markdownj-1.0.2b4-0.3.0.jar") ] />

<cfset javaLoader = new javaloader.JavaLoader(paths, true) />

<cfset markdownProcessor = javaLoader.create("com.petebevin.markdown.MarkdownProcessor").init() />

<cfset html = markdownProcessor.markdown("This is a *simple* example") />

<cfoutput>
#html#
</cfoutput>


The above code will produce the following HTML output:


<p>This is a <em>simple</em> example</p>


OK. So if that's the simple example, what about a more complex example?


# This is an h1

## This is an h2

This is a normal paragraph. Lorem ipsum dolor sit amet,
consectetur adipisicing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua.

* This is a unordered list. Hanging indents allow
you to wrap a list item onto multiple lines
* List item 2
* List item 3

---
These are horizontal rules
***

This is how to *italicize* something. This is _another way_ to italicize something.

This is how to **bold** something. This is __another way__ to bold something.

1. This is an ordered list
2. List item 2
3. List item 3

This is [an example](http://example.com/ "Title") inline link.

[This link](http://example.net/) has no title attribute.

> This is a block quote. Lorem ipsum dolor sit amet,
> consectetur adipisicing elit, sed do eiusmod tempor
> incididunt ut labore et dolore magna aliqua.

This is a code block.
To produce a code block in Markdown, simply
indent every line of the block by at least
4 spaces or 1 tab



And that's the basics of Markdown. Here's a full set of syntax rules: http://daringfireball.net/projects/markdown/syntax. Pretty sweet if you ask me.

8 comments:

  1. FYI in Railo you skip JavaLoader and you can use CreateObjects('java')'s thrid attribute.

    http://blog.getrailo.com/post.cfm/railo-tip-createobject-java

    ReplyDelete
  2. I see on the jMarkdown page that the code was last updated in 2008 and they've only released the JAR file. Are there any known bugs? Any ideas on how you would fix a bug or extend/customize the markdown processor if the need arose? Personally I love markdown and use it all the time on ServerFault and StackOverflow, but I'd be hesitant to include this in a production project with no way to fix or extend things if needed. Thanks for showing how simple it is to use though.

    ReplyDelete
  3. @Peter,

    Very cool. I haven't used Railo too much, but it makes total sense to have a JavaLoader "built-in" to the platform. Hopefully Adobe ColdFusion would add this feature in an upcoming release.

    @Justin,

    There's an Issues tab on the Google code site that lists a couple known issues. Also, MarkdownJ is open source, so you should be able to extend it relatively easily using Java.

    ReplyDelete
  4. Open source and "should be able to extend" are great, but I didn't see anywhere to get access to the source code to actually make edits and recompile on your own. I'm not familiar with Google Code though so it may be somewhere other than "downloads" that I'm missing.

    ReplyDelete
  5. @Justin,

    After you download the .jar file, you should be able to extract and decompile the classes.

    One of the easiest ways to extract the .jar file is to simply change the file extension to .zip, so markdownj-1.0.2b4-0.3.0.jar becomes markdownj-1.0.2b4-0.3.0.zip.

    I haven't done too much with decompiling Java classes, but there was a StackOverflow link to http://java.decompiler.free.fr/ that looks promising.

    ReplyDelete
  6. Interesting. That doesn't seem quite the same as having the original source code but I suppose it could do the trick in a pinch.

    ReplyDelete
  7. You can also check out my wrapper CFShowdown at http://blog.adampresley.com/software-development/cfshowdown-a-markdown-library-for-coldfusion/

    ReplyDelete
  8. IIRC there are even Javascript libraries so you could provide a real-time preview while you're typing it up.

    ReplyDelete