If you are a writer, especially a tech writer, there’s a roiling sea of tools and formats to consider. From DITA to Frame, LaTeX to SGML, Confluence to MediaWiki, you can find a framework for every purpose. And one that keeps coming up, as a lightweight writing format, a lingua franca among other file types, and a lure to get engineers to document their code better, is Markdown. But what is it, and why should you (not) use it?
Update: If you want more information, I actually wrote a book that talks about this (and other Markdown stuff): Markdown Dreams: How to do things with Markdown and Git
John Gruber, a writer and UI designer, invented Markdown in 2004: a lightweight markup language plus a PERL script for converting Markdown to valid, well-formed XHTML or HTML. Its main purpose was to make it easier to create web pages without all those HTML tags getting in the way of the writing process.
Markdown was not intended to replace HTML, but to augment it — it is meant as a writing tool, whereas HTML is a publishing format. Accordingly, its syntax is small: it addresses the subset of HTML tags that specify things which could be conveyed in plain text. In fact, one inspiration for Markdown syntax was the kind of formatting that people use in plain-text email. The idea was to make it very easy to read, write, and edit prose with some formatting, and that the result should be usable as-is.
In a way, it is the limitations of Markdown that make it revolutionary. Other markup languages can do everything Markdown can do — and more. What makes Markdown interesting is that it gets excessive features out of the way of the mechanics of writing. The focus is on the writer first, and capability is added only where it helps with what the writer is trying to do. If you need more than what Markdown provides, you can add some HTML, but the main goal is a simple, uncluttered writing environment.
Of course, these limitations didn’t sit well with everyone. Over the first few years, while most programming languages were developing parsers and libraries for Markdown, many sites were developing their own variations with additional features. Reddit, GitHub, StackExchange, Wordpress, and others created derivative versions of Markdown that provided capabilities not included in the original specification.
There is no perfect tool for writing. As a tech writer, I have spent many years searching for the lost chord: a writing tool suited for both print and web publishing, with an easy review process, content management features that allow sophisticated structuring and reuse, good integration with source control, and so on. Every writing tool has its tradeoffs.
One of the most interesting questions when choosing a writing tool is whether it is capable of semantic formatting. To refresh your memory, semantic formatting is when the document markup reflects the structure or nature of the content itself. Most tools use headers, lists, and even elements like classes or warnings to indicate document structure. The alternative is presentational formatting, which concerns itself with how things look.
In reality, most tools fall somewhere in between or are capable of both. In HTML, for example, there are semantic tags like <strong> and <em> that indicate something about the meaning of those parts of the document as well as their formatting. Presentational tags like <bold> and <italic> create the same visual effect, but lose the semantic value. This matters because semantic cues can be significant in contexts that are important to certain parts of your audience. For example, screen readers for the visually impaired treat semantic tags as part of the meaning of the document and include them in the information presented, but often ignore presentational tags.
As a superset of HTML, Markdown also straddles the line a bit. The markup for bold and italic styles, converted by Gruber’s Markdown Dingus, results in <strong> and <em> tags, implying that preserving some semantic content was part of the idea.
If Markdown took a stronger stand on semantic structure, it would be a better tool for a number of reasons. You can’t indicate a class, a warning, or some other structural element in any meaningful way. Despite the presence of structural elements like headings, Markdown doesn’t really let you say much about the content.
Being weak on semantic tools also makes Markdown content less portable than it otherwise would be. You can’t map element types to each other, which makes it more difficult to convert to other formats.
There is no way to manage longer documents in Markdown, either. You can’t easily incorporate pieces together, reuse content, or even create a table of contents. Once you are managing something larger than a single page of formatted text, Markdown kind of throws up its hands.
Markdown’s beauty — its simplicity — comes without extensibility; the features it has are the features you get. Unable to extend Markdown (especially semantically), developers have resorted to creating their own flavors. These dialects often have their own mutually incomprehensible syntaxes for the same things. There is no canonical Markdown standard. And even if there were, the original specification by Gruber himself contains ambiguities and contradictions that make Markdown hard to rely on.
If all that weren’t enough, the fact that Markdown is a superset of HTML makes it a security risk: when you add HTML tags to Markdown, it is susceptible to XSS attacks. Unlike normal HTML, Markdown is unescaped, stripping away much of the ability to protect against these attacks.
There are a number of other lightweight markup languages that some consider better choices.
Asciidoc, originally designed as a plain text alternative to DocBook, was created with structured writing in mind and is extensible by design. It can generate output in numerous formats (including DocBook, obviously) and is part of Atlas, which O’Reilly uses in producing their manuals.
Restructured Text (ReST) was initially released in 2002, making it older than Markdown. Extensibility is a core principle in its design, but it is already more fully-featured, including footnotes, tables, citations, and tables of contents right out of the box. With all this, it has a comprehensive specification and a single canonical implementation still in development via the docutils project.
Creole is a project that tries to find a common syntax, and looks a bit like both Asciidoc and Restructured Text.
Above all, Markdown does what it was designed to do: it provides a simple, fast environment that lets you get straight to the writing. You can quickly format text in any editor on any platform without even letting your mouse get in the way. It’s easy to learn and the results are easy to read.
I’m a big fan of constraints. Markdown’s limited features keep formatting consistent between documents and between authors because you can’t make choices about font, text size, kerning, margins, or other visual design.
Many tools are Markdown-capable, including favorites like Doxygen, Git, Trello, and Wordpress. Markdown converts easily to just about anything including PDF and slides, and becomes even more versatile when combined with a conversion tool like Pandoc. Markdown is widely used, and because it’s just ASCII text after all, it is future-proof. When our descendants are trying to figure out how to read a PDF file, Markdown will still be sitting there out in the open like a Rosetta stone.
By the way, since it’s just text, it’s easy to manage with any source control tool. That gives you version history and makes it possible to merge and diff Markdown as easily as any other text file.
Because Markdown is a superset of HTML, any HTML file is valid Markdown. That means you can use all the features of HTML to add tables and other elements to your Markdown documents. At the same time, you don’t have to use HTML; you can just keep it simple and readable.
Although there are many flavors of Markdown, a few stand out and are worth mentioning here.
CommonMark was created in 2012 as an attempt to create a standard for Markdown. Gruber did not support the idea of a standard, as he felt that a single syntax would be unlikely to satisfy different users with different needs.
GitHub-Flavored Markdown, which is based on CommonMark, adds features like tables, strikethrough, task lists, and automatic links.
Markdown Extra is another dialect, supported in content management systems like Drupal and MediaWiki. This variant adds elements with ID and class attributes for more semantic power, along with semantic features like footnotes and abbreviations. It also includes formatting features like tables, fenced code blocks, and the ability to use Markdown syntax inside HTML.
MultiMarkdown (MMD) adds tables, footnotes, citations, and other features. It includes a tool to convert Markdown into formats such as HTML, PDF, and OpenDocument.
Here are a few online tools so you can get started experimenting with Markdown and can explore the differences between various dialects.
Hashify and the Markdown Dingus are both tools that let you experiment with Markdown: enter Markdown and see the formatted results rendered instantly.
Babelmark is a tool for comparing the syntax and output of various implementations. You can enter a Markdown fragment and see how it is rendered by different flavors.
Pandoc is a tool that lets you convert among a variety of file formats including Markdown.
There are too many editors to list, but here are a few.
Typora is a minimalistic WYSIWYG editor that uses GitHub Flavored Markdown, available for Mac, Windows, and Linux.
Many editors, such as MacDown and Dillinger, use a split screen to show a live preview of the formatted content as you edit your Markdown directly.
Ghostwriter is a free, open-source, multi-platform Markdown editor that detects when you install Pandoc, MultiMarkdown, Discount, or CommonMark and uses them to export your content to multiple formats.
There you have it. Hopefully this little tour of lightweight markup has clarified and solidified the reasons in your mind why you definitely should (not) use Markdown. And if (when) you do, here are a few resources you might find interesting:
