Summary
Markdown has a lot of users and tools, but it was pointed out that it's limited and has been forked, while AsciiDoc has an extensible architecture.

This suggests that I might want to use AsciiDoc instead for a programming blog. After a bit of exploration, I have decided that the Markdown approach is a better fit for my needs. Here's why:

1. Markdown tools are much more mature than for AsciiDoc. It's definitely possible to set up a working toolchain for AsciiDoc (Here's a live preview for Chrome, and a blog post showing how to set up the toolchain), but I've learned that when I'm writing, any little extra thing I have to think about gets in the way of writing. I've come to like MarkdownPad (which is for Windows, but there are lots of similar tools for the Mac), especially because it has keyboard and menu shortcuts so, while learning Markdown markup isn't hard, I don't have to keep the syntax in my head. When I'm writing, I want to write, not remember markup syntax.
2. While AsciiDoc is evolving in all kinds of interesting ways (I've used Slidy to create slide presentations, for example), Markdown is quite adequate for writing programming blog entries. Combine that with #1 and Markdown seems the best fit for me.

I'll keep my eye on AsciiDoc. One nice thing is that both Markdown and AsciiDoc have the same goal and similar syntax, so switching from one to the other isn't that hard (especially when you have good tools).

The free version of MarkdownPad supports standard Markdown. The paid "Pro" version (only $14.95) supports the two flavors of extension to Markdown:

1. Markdown Extra includes some additional formatting for things like tables and definition lists.
2. GitHub Flavored Markdown seems to be, effectively, a superset of Markdown Extra except possibly for definition lists. It also seems to have more table layout options. Most importantly to me, it contains syntax-colored highlighting for code blocks (both extensions provide a way to mark code blocks without indenting them). This is language-specific highlighting, and the only drawback is that the highlighter isn't local -- it requires an engine that lives on the web, so there's can be a brief pause for highlighting. If you don't like that, or you're not connected, you can go to Tools|Options|Markdown and choose the offline version, which produces code formatting but without coloring. Later you can turn the online mode back on and get the coloring again. The MarkdownPad programmer is apparently looking at bringing the colorizer into the offline version, but right now it's reasonably tolerable.

MarkdownPad is kind of a mini static site generator; it produces HTML and inserts a stylesheet, and you can find or make your own style sheet for automatic insertion. For blogs that don't need anything more than this, MarkdownPad might be enough -- you could just take this output and upload it somewhere like Github Pages and be done. It's unclear to me right now whether this will produce my desired results, so I'll at least look at some static site generators. Jekyll appears to be the most popular of these.

Talk Back!

Have an opinion? Readers have already posted 3 comments about this weblog entry. Why not add yours?

RSS Feed

If you'd like to be notified whenever Bruce Eckel adds a new entry to his weblog, subscribe to his RSS feed.

Digg | del.icio.us | Reddit

About the Blogger

Bruce Eckel (www.BruceEckel.com) provides development assistance in Python with user interfaces in Flex. He is the author of Thinking in Java (Prentice-Hall, 1998, 2nd Edition, 2000, 3rd Edition, 2003, 4th Edition, 2005), the Hands-On Java Seminar CD ROM (available on the Web site), Thinking in C++ (PH 1995; 2nd edition 2000, Volume 2 with Chuck Allison, 2003), C++ Inside & Out (Osborne/McGraw-Hill 1993), among others. He's given hundreds of presentations throughout the world, published over 150 articles in numerous magazines, was a founding member of the ANSI/ISO C++ committee and speaks regularly at conferences.