Virtuous Programmer Adventures of an Autodidact



What's it for?

Markdown is a lightweight markup language which allows its user to create documents in a variety of formats. Unlike many other markup languages like HTML and LaTeX, readability of the sourcecode was one of the top priorities in Markdown's design. Its creator, John Gruber, based its syntax on how we format plain text emails to make it as readable as possible. For example: to emphasize text, you use "*important*" to get "important".

For people who are accustomed to working in plain text, this is an excellent tool to create documents others will want to read while still using text editors and other tools that they are accustomed to.

Where to get it

Markdown is only a syntax specification for which there are several implementations. For most purposes I've found Pandoc to be excellent. Pandoc reads a superset of Markdown and writes out in a multitude of formats including HTML, PDF(with pdflatex) and Docbook.

How to Write with Markdown

Here I'll give 4 commonly used formatting as an example. These should be be sufficient for many simple documents:

  • Section Headers
  • Links
  • Lists
  • Code

Section Headers

There are two ways to denote Section Headers which can be mixed freely. The two highest level headers of can be marked by underlining as in:


  1. First-level heading
  2. ===================
  4. Second-level heading
  5. --------------------

Renders as:

First-level heading

Second-level heading

All levels can be marked using # marks preceding the text:


  1. # First-level heading
  3. ## Second-level heading
  5. ### Third-level heading

Renders as:

First-level heading

Second-level heading

Third-level heading

The maximum number of levels depends on the format that it's converted to. As an example, HTML allows for 6 levels.


Links are written in the format [<link name>](<url> "<title>") where the title is optional. For example, [Python]( "Python's web site") renders as: Python


Lists may either be bulleted or numbered:

Bulleted List Markdown:

  1.    * First
  2.   * Second
  3.   * Third

Renders as:

  • First
  • Second
  • Third

Numbered List Markdown:

  1.    1. First
  2.   2. Second
  3.   3. Third

Renders as:

  1. First
  2. Second
  3. Third


Code can be entered inline by surrounding it with back quotes, `like this` or by indenting by 4 or more spaces:


  1.     if inCodeBlock:
  2.       return True

Renders as:

if inCodeBlock:
  return True

Generating Documents from Markdown Using Pandoc

Once you've downloaded Pandoc from its site and installed it, you can generate a variety of documents from your Markdown text. To see the complete list type "pandoc --help" at the command line.

To generate HTML documents at the command line use "pandoc <markdown document>.mkd -o <html document>.html". Pandoc determines what the format of the input and output types are from their extensions.

Final Words

Markdown is a readable markup language that covers a significant proportion what you need to generate formatted documents. Unfortunately it does lack some features. There is no notation for tables, footnotes and several other fairly common features in documents available in the original Markdown standard. To compensate for this, a variety of supersets have been create. Pandoc's extensions, Markdown Extra and MultiMarkdown are all commonly used.

If you want to play with Markdown a bit to get your feet wet, this blog is also written using Markdown and the comments section supports it. Feel free to experiment.


Posted by Frank Berthold

Filed under: Markup Leave a comment
Comments (1) Trackbacks (0)
  1. This is probably the most concise explanation of markdown I’ve seen. A lot of sites allow you to use markdown for formatting your comments or submissions, and I never knew all the features it offers!


Leave a comment

No trackbacks yet.