Markdown => Tutorial in 1 Step

When I wrote my Ruby Readline tutorial I felt I came up with a cool concept. I started with a Markdown file, translated it to html, and I used the headers to generate a Table of Contents on the fly.

table of contents

It didn’t take me long to realize that I could turn this into a framework where I could turn any Markdown file into a tutorial exactly like this one. So with surprisingly little work I modified the scripts to work with any markdown file and the html automatically generated from the standard script.

I called this markdownorial. Laugh all you want at the name, but I still think the concept is very cool. I’ll probably be using this more and more to automatically generate and format a pretty cool looking tutorial from a single markdown file. The start to finish time for a project like this has instantly dropped to just the raw content part, no design or coding needed!

Advantages include:

  • Writing Markdown is very fast and efficient.

  • Time is spent writing the content. Not messing with design,

  • Table of Contents is automatically built for you.

  • Useful permalinks are automatically generated. Very useful when passing around links.

  • Clean user interface that focuses entirely on the content but the Table of Contents is always available!

  • Git Repository means if I update the design its just a `git pull` away to get the update.

Right now the tutorials shows up elegantly in all standards compliant browsers. Safari/Webkit and Chrome display it perfectly. Opera has some very minor Unicode issues but displays everything perfectly. Firefox has some separate Unicode issues and if you don’t have the latest version it has some working but slow animation. Overall, its entirely usable for people using decent browsers.

Let me know what you think. Feel free to use it and improve it. Its all up on Github.

2 Responses


Neefra on May 25, 2009 at 5:06 am  #

well i m now considering to learn Ruby Readline , after reading your post.
kindly share any resource from where i will learn from grass root level of language.


Joseph Pecoraro on May 25, 2009 at 6:02 pm  #

Just so everyone knows, Markdownorial is a generic framework unrelated to Ruby Readline. That is just the example tutorial that I wrote.

@Neefra: Thats great. Here is some more information. Ruby and Readline are really two different things.

Ruby is a general purpose scripting language. You can find tutorials and more information about it at:

Readline is the name of a GNU library which provides a number of useful functions when working with a command line interface. Command history, control keys to move the cursor more efficiently, etc. You can learn more about the library at:

The tutorial I linked to above, my Ruby Readline tutorial, shows how you can use them both together. Ruby comes with built-in support for using the GNU readline library, however documentation on the subject was lacking. I decided to provide more thorough documentation with the help of an expert, Michael Fellinger.

Add a Comment