The Markdown book and a bit of history
April 5, 2013 at 11:36 PM by Dr. Drang
The day before I left on vacation, I got an email from David Sparks with a link to the PDF of the Markdown book he and Eddie Smith wrote. The freebie was nice, but even nicer was that David remembered that I don’t have an iPad and couldn’t use the iBooks version.1 No wonder everybody likes him.
So now it’s a couple of weeks later, the book is a super best-seller, and you’ve already heard how good it is. What can I add? Well, I thought I’d point out what I thought was most interesting and useful in the book, pick a nit or two, and point out a couple of historical facts.
First, you may be surprised to find that in a book that runs 139 pages, only 30-35 pages are devoted to the syntax of Markdown and MultiMarkdown. This is an indication of how simple Markdown’s syntax is—there just isn’t that much to learn. So what’s the rest of the book about? Mostly it’s about the many ways you can use Markdown in your writing. Three full chapters and part of a fourth cover the various utilities available for writing in2 and processing Markdown on the Mac, Windows, and iOS. Another is filled with interviews of real people and how they use Markdown to get their work done.
This emphasis on the Markdown ecosystem is exactly right. As the popularity of Markdown has mushroomed in the last few years, the number of Markdown tools has grown with it. The choices are overwhelming, especially to new users, and David and Eddie provide the guidance needed to make your way through the thicket.3
If you’re a longtime user of Markdown you probably think you don’t need this kind of guidance, and you may well be right. But you’ll probably want to give (or at least recommend, you cheapskate) the book to friends who’ve heard about Markdown but don’t know where to start. There’s also a tendency for Markdown users to over-evangelize it, alienating the people they want to bring into the fold. Let David and Eddie do the evangelizing for you—they’re better at it.
An example is how the book treats indenting. Indenting is needed when you’re inserting code samples and sometimes when you’re making a list. There are rules about what constitutes a Markdown indent, and if I were explaining it, I’d get into what those rules are and I’d probably throw in my prejudice against tabs, too.4 Newcomers don’t need that crap, and Eddie—who narrates both the code and list screencasts—wisely avoids it. Most people will tap the Tab key when they want to indent and it’ll work just fine.
There is one aspect of the book, though, that I found wanting. David and Eddie talk briefly about using Markdown in a WordPress blog and link to the WP-Markdown plugin. I’ve been using Markdown in a WordPress blog for ages and I’d never heard of that plugin. And after I looked into it, I was glad that I hadn’t. According to its FAQ, it converts your Markdown into HTML before it gets stored in the WordPress database. I find this distasteful because I want my posts saved the way I wrote them—in Markdown. David and Eddie agree:
While blogging platforms that support Markdown add convenience, it is worth considering the longevity of your writing. Keep in mind that web browsers are designed to render HTML, not Markdown. If your blogging tool of choice goes the way of the dodo, you cannot be sure how your words will look. This is something to keep in mind anytime you are evaluating a new tool that promises to make your life easier by doing something that is, frankly, pretty darn easy to do yourself. One solution is to keep your own archive of blog posts as Markdown text files.
Given their (correct) preference for storing Markdown as Markdown, they shouldn’t have linked to a plugin that doesn’t.
Interestingly, WP-Markdown is built around a WordPress plugin (and general PHP-based Markdown utility) called PHP Markdown Extra, written by Michel Fortin. This—or its simpler sibling PHP Markdown—is the plugin David and Eddie should have mentioned in the book, both because it matches their philosophy by storing the posts as Markdown and because Michel Fortin was an important figure in making Markdown what it is today.
Back when WordPress was gaining momentum after Six Apart changed the license for Movable Type, PHP Markdown was the only way to write a WordPress blog in Markdown. Michel was also one of the first people to translate John Gruber’s original Perl version of Markdown into another language. In doing so, he found bugs and discrepancies in the Markdown spec that were fixed in later versions.
Michel was more than just an implementer. He was a strong presence on the Markdown mailing list, guiding the syntax of Markdown’s advanced features. PHP Markdown Extra was where we first found tables, definition lists, and underscores that didn’t generate italics when they were used within words, e.g., this_file_name.
PHP Markdown Extra was announced on the mailing list on July 25, 2005, just a day before Fletcher Penney announced the infant version of MultiMarkdown. At the time, MultiMarkdown’s main feature was the metadata header and the ability to generate LaTeX; as I recall, Fletcher later took the syntax for tables and definition lists from Michel’s spec.
It’s not that I think David and Eddie should have included an acknowledgement of everyone who contributed ideas to Markdown, but Michel is a special case. If the second edition fixes that omission, the book will be perfect in every way.
-
Although the PDF version has the advantage of being readable/watchable/listenable on any device (the screencasts and audio files are bundled with the PDF), I’m pretty sure that if I had an iPad I’d go with the iBooks version. It’s much easier to just click on a screencast than to dig through a folder to find it. ↩
-
Personally, I’m of the opinion that “Markdown editors” are unnecessary, but I recognize that I’m in the minority. ↩
-
Can there be a thicket of mushrooms? My mixed metaphor alarm may need recalibration. ↩
-
An entirely justified prejudice, I might add. ↩
