Why I like Markdown

I format my articles using Markdown, a lightweight syntax designed to emulate the simple markup style commonly used in email messages. For example, if you would like to make text bold, just put asterisks around it. If you would like to make a list, just put a dash in front of each item. Overall, I’m happy with the change, as it has simplified the process for me to publish online. I can write with any text editor or word processor and then Markdown will convert my text to nicely formatted HTML.

Markdown is both a markup language and tool to convert the markup to HTML. The syntax for Markdown is simple and adds very little bulk to my text. Effectively, the only change made when I write was to add a small amount of formatting for the Markdown hyperlinks and headings. Markdown’s creator, John Gruber, wrote Dive Into Markdown, an essay describing his design goals, soon after he released the software in 2004. It is well written and worth reading.

I now prefer to keep my documents in Markdown over HTML as they are smaller, easier to read, and I can convert them to modern standards-based HTML on demand. I prefer this setup to WYSIWG tools or graphical HTML editors as viewing the content in the same browser version is the only way to ensure that you will see the same HTML rendering as your readers. When the W3C updates the HTML specification or the Markdown conversion tools add new features, I can just install a new version of Markdown. I don’t need to modify my original text. Markdown is great for producing basic HTML documents like blog entries or simple web pages, but it is not well suited for long, complex, or highly formatted documents. There are several extensions to Markdown that add features to publish more specialized and complex documents.

If you would like to try Markdown for yourself without installing software, the Markdown Web Dingus or PHP Markdown Dingus will both give you a live preview of any Markdown formatted text you type. Markdown works on Mac OS X, Windows, and Unix/Linux and is widely supported as a plugin for most popular blog and wiki software. The reference version is written in Perl and developers have ported Markdown to Python, C, JavaScript, and other languages.

Gruber also wrote SmartyPants, which transforms plain text to include nice typographic elements such as curly quotes, en-dashes, em-dashes, and ellipses. Many implementations of Markdown include support for SmartyPants by default. Markdown has a liberal BSD-style license that makes it easy for developers to embed it in other packages. There are several Markdown test suites that can test compatibility between versions, including one that ships with the reference version of Markdown. Wikipedia has a good technical comparison between lightweight markup languages if you would like to see how Markdown differs from similar projects.

Markdown Implementations and Utilities

These days, I write almost everything using the TextMate editor on Mac OS X, which includes support for SmartyPants, Markdown, and PHP Markdown extra. I use the QuickLook Markdown plugin when I want to quickly see a formatted version of a Markdown file from the Finder.

Markdownify converts from HTML to Markdown. The script is available as a web-based conversion tool or you can run the script on your own machine. It supports PHP Markdown Extra as well.

PHP Markdown Extra by Michel Fortin is a PHP implementation of Markdown that supports definition lists, footnotes, tables, and intermix HTML with Markdown. Fortin also created a PHP version of SmartyPants unsurprisingly called PHP SmartyPants.

MultiMarkdown by Fletcher Penney supports extensions to the Markdown syntax such as footnotes, tables, bibliographic citations, image attributes, internal cross-references, glossary entries, and definition lists. MultiMarkdown first converts the plain text to XHTML and then uses XSLT transforms convert the XHTML into HTML, LaTeX, PDF, or RTF. It includes many features similar to PHP Markdown Extra. Penny’s MultiMarkdown Bundle for TextMate adds support for the MultiMarkdown variant.

Discount by David Parsons is a C version of Markdown, PHP Markdown extra, and SmartyPants that focuses on speed.

Pandoc by John MacFarlane can convert from Markdown, HTML, reStructuredText, and LaTeX to “reStructuredText, HTML, LaTeX, ConTeXt, PDF, RTF, DocBook XML, OpenDocument XML, ODT, GNU Texinfo, MediaWiki markup, groff man pages, and S5 HTML slide shows.” Pandoc includes Markdown extensions for definition lists, embedded LaTeX equations, footnotes, and tables. Pandoc is written in Haskell, which and currently requires a bit of tweaking to make it work on Mac OS X 10.6/Snow Leopard.

Babelmark, the Markdown Testbed, allows you to compare the output of different Markdown implementations.

* This article originally appeared as Markdown Simplifies Writing for the Web in my Messaging News “On Message Column.”