Pandoc vs Multimarkdown

Baldur Kristinsson edited this page Sep 8, 2016 · 36 revisions

This is an evolving document comparing features of Pandoc (1.17) and Fletcher Penney's Multimarkdown (version 3).

Note: as of v 1.10, pandoc allows limited conversion between markdown dialects. Not all features are yet supported, and conversions will not be perfect. But they should help for those who want to migrate.

pandoc → multimarkdown:

pandoc -s -t markdown_mmd

multimarkdown → pandoc:

pandoc -s -f markdown_mmd -t markdown

Input formats

Format Pandoc MMD
markdown
reStructuredText
Textile
HTML
LaTeX
DocBook
MediWiki
OPML
Emacs org-mode
Haddock
txt2tags
Word docx
EPUB

Output formats

Format Pandoc MMD v2 MMD v3
XHTML 4
HTML 5
LaTeX
ConTeXt
markdown
Word docx
OPML
OpenDocument XML
ODT
Textile
reStructuredText
RTF
DocBook
Texinfo
Groff man
Mediawiki
Emacs org-mode
EPUB v2
EPUB v3
Slidy
S5
dzslides
Beamer
AsciiDoc
FictionBook 2
DokuWiki

Features in pandoc but not MMD

Templates

Pandoc includes a templating system for standalone documents. Default templates are included, but users can override them with custom templates.

Delimited code blocks

Pandoc supports delimited code blocks, like this:

~~~~ {.haskell}
fibs = 1 : 1 : zipWith (+) (tail fibs) fibs
~~~~

or

``` haskell
as = 1 : as
```

Code highlighting

Pandoc highlights code marked with a language in a delimited code block. No external program is required. Over 80 syntaxes are supported.

Example lists

Pandoc supports a syntax for running example lists that are incremented throughout a document:

(@one)  My first example will be numbered (1).
(@)  My second example will be numbered (2).

Explanation of example (@one).

(@)  My third example will be numbered (3).

Fancy list numbers

Pandoc allows ordered lists to have different numbering styles and delimiters; these are recorded and reproduced, where possible, in the output format.

(a) My list
(b) Lowercase letters
    i. Roman sublist
    ii. Next

List start number

In standard markdown the starting number of an ordered list is ignored, so all lists start with 1. Pandoc allows lists to start with any number.

Strikeout

Pandoc supports strikeout ~~like so~~.

Superscript

Pandoc supports superscripts: mc^2^.

Subscript

Pandoc supports subscripts: H~2~O.

Inline footnotes

Pandoc allows inline footnotes, like this^[Here's a note.].

Scripting

Pandoc has a Haskell API for convenient scripting. The AST can be modified between parsing and writing. For examples, see Scripting with pandoc. There is also a python module for writing pandoc filters using python.

Features in MMD but not pandoc

Glossary

MMD turns specially marked footnotes into glossary entries in LaTeX:

[^glossaryfootnote]: glossary: term (optional sort key)
    The actual definition belongs on a new line, and can continue on
    just as other footnotes.

Features implemented differently in pandoc and MMD

Raw TeX

Pandoc allows raw TeX commands and environments in markdown. These are passed unchanged to LaTeX and ConTeXt writers, and ignored in other writers.

MMD allows raw TeX inside HTML comments. It also supports the LaTeX \input command, while pandoc does not.

Raw HTML

In pandoc, text within HTML block tags is parsed as markdown, unless the --strict option is used. In MMD, it is parsed as markdown if the --process-html option is used, or if the block tag contains the markdown attribute.

Citations and bibliography

Pandoc has extensive support for automatic citation and bibliography generation that works in every output format. Many existing bibliography database formats (including BibTeX, MODS, and EndNote) can be used. Citations are written in markdown as follows:

Blah blah [see @doe99, pp. 33-35; also @smith04, ch. 1].
Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].
Blah blah [@smith04; @doe99].
Smith says blah [-@smith04].
@smith04 [p. 33] says blah.

They will be formatted in the output according to a CSL stylesheet specified on the command line, and a bibliography will be added automatically if the style calls for it. Many, many styles are available. You can even switch freely between author-date and footnote styles, and pandoc will do the right thing with surrounding punctuation.

MMD has much more rudimentary citation support. Example:

This is a statement that should be attributed to
its source[p. 23][#Doe:2006].

And following is the description of the reference to be
used in the bibliography.

[#Doe:2006]: John Doe. *Some Big Fancy Book*.  Vanity Press, 2006.

There is no automatic citation/bibliography formatting, unless LaTeX output is used (in which case natbib and bibtex are used).

Math

Pandoc allows inline and display LaTeX math. $ delimiters are used for inline math, and $$ for display math. If LaTeX macros have been defined in the document, they are automatically applied to all math (and this works even if the output format is not LaTeX). A variety of HTML output options are possible, including direct conversion to MathML, faking it with unicode, raw LaTeX for use with MathJax, and images.

MMD also allows inline and display LaTeX math, but \\( delimiters are used for inline math, and \\[ for display math. MathJax is used in HTML.

Tables

Pandoc tables are designed to look natural in plain text (but require a monospace font for readability). Table cells can span multiple lines. Table cells can contain block-level elements (multiple paragraphs, lists, code blocks). Row spans and column spans are not currently supported. Captions are supported. Cell alignment is determined implicitly, based on the position of the column header. Relative cell widths in the output format will mirror the relative widths of the columns in the markdown source.

Simple table:

  Right     Left     Center     Default
-------     ------ ----------   -------
     12     12        12            12
    123     123       123          123
      1     1          1             1

Table:  Demonstration of simple table syntax.

Multiline table:

----------- ------- --------------- -------------------------
   First    row                12.0 Example of a row that
                                    spans multiple lines.

  Second    row                 5.0 Here's another one. Note
                                    the blank line between
                                    rows.
-------------------------------------------------------------

Grid table (generated using Emacs table mode):

+---------------+---------------+--------------------+
| Fruit         | Price         | Advantages         |
+===============+===============+====================+
| Bananas       | $1.34         | - built-in wrapper |
|               |               | - bright color     |
+---------------+---------------+--------------------+
| Oranges       | $2.10         | - cures scurvy     |
|               |               | - tasty            |
+---------------+---------------+--------------------+

As of 1.10, pandoc also offers pipe tables as in PHP markdown extra; these can be used when it is inconvenient to line up columns. Pipe tables look like this:

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

  : Demonstration of simple table syntax.

MMD tables use | characters to indicate columns, so the tables are more readable using a proportional spaced font. Colons are used to indicate column alignment. Column spans but not row spans are supported. Captions are supported. Cells are limited to a single line and cannot contain block-level elements.

MMD table:

|             |          Grouping           ||
First Header  | Second Header | Third Header |
 ------------ | :-----------: | -----------: |
Content       |          *Long Cell*        ||
Content       |   **Cell**    |         Cell |

New section   |     More      |         Data |
And more      |            And more          |
[Prototype table]

Pandoc's pipe tables are similar, but do not have all of the features of MMD pipe tables (sections, colspan, rowspan, grouping).

Metadata

Both pandoc and MMD allow a title block at the beginning of the document. A pandoc title block contains title, author, and date (though other metadata can be specified by the command line). By convention, the first line preceded by % is the title, the second (if present) the authors, and the third (if present) the date. MMD allows arbitrary metadata fields to be specified using a key : value format. Quite a few document features can be controlled using metadata.

MMD does not parse the contents of metadata fields as markdown. Pandoc does, allowing titles and authors to include arbitrary markdown formatting (even footnotes).

An advantage of MMD's system is that arbitrary metadata fields can be specified. A disadvantage is that a document starting with a line containing a colon may be unexpectedly interpreted as beginning with metadata. Try beginning a document with "This above all: to thine own self be true." Note also that MMD's metadata fields cannot contain blank lines.

As of version 1.12, pandoc allows YAML metadata blocks to be inserted anywhere in a document. Metadata fields may contain formatted text.

Pandoc title block:

% My title with `markdown` *emphasis*
% John MacFarlane
  John Doe
% September 6, 2004

Pandoc YAML metadata block:

---
title: My title with `markdown` *emphasis*
author:
- John MacFarlane
- John Doe
doi: 10.234234.23424/x
date: September 6, 2004
abstract: |
  A formatted abstract here.

  May contain multiple paragraphs.
...

MMD metadata:

Title:  A New MultiMarkdown Document  
Author: Fletcher T. Penney  
        John Doe  
Date:   July 25, 2005  

MMD YAML-styled metadata:

---
Title:  A New MultiMarkdown Document  
Author: Fletcher T. Penney  
        John Doe  
Date:   July 25, 2005  
---

Image and link attributes

MMD supports image and link attributes using the following syntax:

[image]: http://path.to/image "Image title" width=40px height=400px
[link]:  http://path.to/link.html "Some Link" class=external
         style="border: solid black 1px;"

From version 1.16 onwards, Pandoc supports both inline and reference-style image and link attributes, using curly brackets as delimiters:

An inline ![image](foo.jpg){#id .class width=30 height=20px}
and a reference ![image][ref] with attributes.

[ref]: foo.jpg "optional title" {#id .class key=val key2="val 2"}

Parsing of MMD link and image attributes can be enabled with the extension mmd_link_attributes.