MarkDown, Textile, RDoc, choose your foe

Recently i used all 3 of them for various project documentation, and somehow all of the are broken…



  • Looks like natural text
  • Simple, mostly elegant syntax


  • Lists can destroy your layout, try this:
     - test
    ### Heading

    The heading will be in your list, thats just wtf… (adding <span></span> before the heading helps)

  • No tables…
  • Some editors truncate the double space used for linebreaks
  • No numbered list, except you add 1. 2. etc yourself



  • Looks weird with h2. h3. but thats kind of ok…
  • You need a free line after each heading, which makes the layout look bloated, especially if you got a lot of sub-headings
  • Line break = <br /> very elegant…



  • You can use your RDoc skills for documenting ruby


  • No linebreaks, not even <br/> works….
  • to highlight code you have to use <tt>CODE</tt> very elegant…


  • You can use html to hack most of the things that do not work, but that somehow defies the purpose…

So my personal favorite is markdown, elegant, and if you know you have to look out for those lists its somewhat ok…

But if possible i would switch to RDoc, since then i would not have to make a mental switch while documenting code.

Id like to hear your opinion, or at best a “no thats wrong, you can do xxx with yyy” 🙂

One thought on “MarkDown, Textile, RDoc, choose your foe

  1. This is an interest article. I am surprised why no one has commented. I am going to try sticking with RDoc for the same reason you mention: no mental switch.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s