Rouletteload900

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.

The AsciiDoc syntax is more concise than (or at least as concise as) Markdown. At the same time, AsciiDoc offers power and flexibility without requiring the use of HTML or “flavors” for essential syntax such as tables, description lists, admonitions (tips, notes, warnings, etc.) and table of contents. Today I want to explain why Markdown is a poor writing tool that you should avoid using in your documentation. Markdown is the most renowned lightweight markup language on the Internet.

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.

Adoc Markdown Schedule

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.

Have an opinion?Readers have already posted3commentsabout this weblog entry. Why notadd yours?

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

AsciiDoc Markdown Lang

AsciiDoc Markdown is a human-readable lightweight markup language format, equivalent to text formatting syntax conventions created using any text editor and read “as-is” or rendered format tool-chains

Webmix Nutzer:

Symbaloo-er, die diesen Webmix angeschaut haben, schauten auch:

Adoc Markdown Code