pandoc markdown and org-mode: a comparison

I’ve been experimenting a bit with both markdown and org-mode for doing writing and blog markup. These are just some notes. I’ve been using markdown for general writing, and org-mode for project management for a while.


Markdown was originally developed by John Gruber as a lightweight markup language. Since then it’s been adopted by dozens of different implementations and possibly hundreds of web sites as an alternative to html or ubb code. Some of the typical constructs look like the following:

# A Heading 1

## A Heading 2

1. A numbered list.

* A bulleted list.

A regular paragraph.

[A link to google](

![An image](http://....jpg)

This is just a sample. One of the problems faced with Markdown has been the lack of a clear standard. The original specification was ambiguous on some key points. Various implementations added their own expansions. CommonMark is an attempt to bring some order to this. Pandoc is one of the more useful tools for converting to just about any format.


Org-mode is an organizer and outlining tool for GNU emacs. The emacs mode includes todo lists, complex organizing, and tag searching. It also has a number of export functions, including to HTML, and is used as a blogging tool. The markup used above in org-mode:

* A Heading 1

** A Heading 2

1. A numbered list.

- A bulleted list.

A regular paragraph.

[[][A link to google]]

[[http://....jpg]] (an image)

For most of the rest of the discussion I’ll use markup syntax as the base example.

structural markup

Markdown tends to produce minimal html while org-mode defaults to adding tags needed for features such as a table of contents or section folding. Here’s an example of header-paragraph markup:

# Heading 1

The quick brown fox jumped over the lazy dog.

Using markdown I get:

<h1>Heading 1</h1>
<p>The quick brown fox jumped over the lazy dog.</p>

Using org-mode I get:

<div id="outline-container-sec-1" class="outline-2">
<h2 id="sec-1"><span class="section-number-2">1</span> Heading 1</h2>
<div class="outline-text-2" id="text-1">
The quick brown fox jumped over the lazy dog.

Markdown by default gives me minimal html sections that can be inserted into any page or CMS. org-mode html output defaults to a full page with table of contents, footer information, and stylesheet.


Org-mode seems to recognize images only if they’re local to the file. The html output filter didn’t recognize images served over http at all.

Markdown wasn’t much better due to ambiguities and extensions in the handling of images. Markdown specification for a stand-alone image tag would be:

![This is the caption](/url/of/image.png)

Depending on how you use markdown, “This is the caption” is converted to alt tag and optionally a caption. The resulting HTML is.

<div class="figure">
<img src="/url/of/image.png" alt="This is the caption" />
<p class="caption">This is the caption</p>

This is glossing over where the image is actually served from. So in the end, it might just be easier to replace those links in the wordpress than to try to style them, or pass raw html.


I think that org-mode really shines when you need the advanced folding, to-do tracking, or are working on a page with multiple sections. For most other tasks, I’m finding markdown sufficient.


2 thoughts on “pandoc markdown and org-mode: a comparison

    1. Org-mode didn’t recognize the links as images because I was pulling the images from another site. In the end, it was just easier to use the blogger or wordpress image publishing tool to upload and embed the image with caption.


Comments are closed.