The Artima Developer Community
Sponsored Link

Weblogs Forum
Markdown vs. AsciiDoc

2 replies on 1 page. Most recent reply: Dec 5, 2014 3:59 PM by Phil Denkins

Welcome Guest
  Sign In

Go back to the topic listing  Back to Topic List Click to reply to this topic  Reply to this Topic Click to search messages in this forum  Search Forum Click for a threaded view of the topic  Threaded View   
    Next Topic
Flat View: This topic has 2 replies on 1 page
Bruce Eckel

Posts: 875
Nickname: beckel
Registered: Jun, 2003

Markdown vs. AsciiDoc (View in Weblogs)
Posted: Jul 16, 2014 10:15 AM
Reply to this message Reply
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.
Advertisement

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.


Matej Cepl

Posts: 6
Nickname: mcepl
Registered: Jun, 2007

Re: Markdown vs. AsciiDoc Posted: Jul 17, 2014 11:36 AM
Reply to this message Reply
Hi, Bruce,

there two problems I see with your quest. First you seem to be confusing a bit document format with the software to write it. Concerning the software for writing text I cannot do better than to cite the Internet-late Mark Pilgrim_:

Here’s the basic problem: you’re writing a text editor. Stop doing that. It’s 2007.

.. _Pilgrim:
https://web.archive.org/web/20110928020441/http://diveintomark.org/archives/2007/01/21/wrongroom

Well, it’s not 2007 and it is even sillier than that. Just use your favorite ``$EDITOR`` with the appropriate mode/plugin/bundle for the document format you want to edit (if you tell me that your ``$EDITOR`` doesn’t support extensions than get the one which does, but I am sure you use something reasonable).

Concerning the document format itself I have not much to say. Although I prefer ``reStructredText`` to ``AsciiDoc`` I don’t have much opinion (and not enough experience with the latter), except for very hearty approval of **NOT** using Markdown. I am one of the people who took over (temporarily until the inheritance proceedings settle down) maintainership of html2text_ package after the late (this time really) Aaron Swartz. The output of this script is actually not just a plain text as would its name suggest, but Markdown (Aaron was working with John Gruber on the original design). Therefore (and because of GitHub) I had to study a little bit of the current situation with Markdown. The result of this research is that I want to avoid any contact with this swamp of competing endless messy semi-standards and hacks as much as possible. ``rST`` seems like really designed language comparing to this random generator of random attempts to standart (thinking about CDDB_ and CADT_ in this context).

.. _html2text:
https://github.com/html2text/html2text
.. _CDDB:
http://www.jwz.org/doc/cddb.html
.. _CADT:
http://www.jwz.org/doc/cadt.html

Phil Denkins

Posts: 1
Nickname: phil123
Registered: Dec, 2014

Re: Markdown vs. AsciiDoc Posted: Dec 5, 2014 3:59 PM
Reply to this message Reply
Asciidoc (using Asciidoctor) is definitely preferable.

* it has extensive markup
* the new Pro Git book is written in asciidoctor ( https://github.com/progit/progit2 )
* O'Reilly Atlas (the webbased publishing system) uses Asciidoc
* Even Linus Torvalds likes Asciidoc! (check his comments on google plus)

Flat View: This topic has 2 replies on 1 page
    Next Topic Topic: Concurrency with Python, Twisted, and Flex


Sponsored Links



Google
  Web Artima.com   

Copyright © 1996-2014 Artima, Inc. All Rights Reserved. - Privacy Policy - Terms of Use - Advertise with Us