004.55 Markdown CLI Evaluation

A comparative evalution of open source CLI Markdown processors: discount markdown, hoedown, multimarkdown and pandoc.

View the markdown test page at md_evaluation/md_evaluation.md.

Contents

Objectives • Process • Observations • Resources

Objectives ^▴

1. Markdown Syntax. Find, to the extent possible, a common set of markdown syntax including certain extensions.
2. CLI Settings. Find settings which produce the most similar markdown output.
3. Extension Support. Evaluate extension support for footnotes, piped tables, fenced code, and LaTeX math.

Process ^▴

1. Install 'multimarkdown' (which installs as markdown), 'hoedown', and 'pandoc' as command line tools.

   • Uninstall 'multimarkdown' (brew uninstall multimarkdown) and install 'discount' (which installs as markdown) to run tests for discount.

2. Review/Edit source markdown file "md_evaluation.md".

3. Review "test.sh". Edit options as needed. Run ./test.sh.

4. Compare output. The a and b versions allow comparison what output changed for some settings change for the same CLI tool. The txt and html allows for comparison of raw output and how the output renders in a browser.

Note: Discount and MultiMarkdown have install conflicting execution binaries named markdown. Thus, Discount markdown and MultiMarkdown markdown are mutually exclusive brew installs. However, Discount markdown can be manually installed somewhere not on $PATH and scripted with /FULL/PATH/TO/markdown.

Observations ^▴

The source document md_evaluation.md evolved and evolves to contain details on common syntax and notes on various markdown feature.

Some of the major findings are noted here below.

LaTeX demarkation syntax

	$, $$	\\(, \\[	\(, \[
raw html			✓
discount markdown			✓
hoedown	✓	✓
multimarkdown	✓	✓
pandoc	✓	✓	✓

Note: Use of \(, \[ single escape syntax disallows escaping ( and [ for other purposes. hoedown does not have expressly enable/disbale control over dollar sign $ vs. double backslash \\ syntax. pandoc can expressly enable/disable each of the three syntax.

discount markdown

• html fenced code. discount markdown fenced html with ∼∼∼ html does not generate a useable code block. Angle brackets are not converted to html entities. The enclosing <pre><code> tags are not produced. Workaround Options: (1) fence the html with ∼∼∼ markup or (2) write an html codeblock as raw html in the markdown file.

hoedown

• C Library. MacDown uses hoedown C library when rendering markdown.
• LaTeX guessing. --math option alone can produce incorrect and unexpected output. The combination of --math and --math-explicit did produce predictable, reliable results in these tests.

multimarkdown

• C Library

pandoc

• Options. Pandoc has the largest set of enable/disable options. see PandocMarkdownOptions.md
• <pre><code> Pandoc generates <pre class="markdown"><code> instead of <pre><code class="language-markdown">.

Resources ^▴

• DaringFireball: markdown ⇗ Implementation: Perl v1.0.1 2004.12.17
• Discount markdown ⇗, github ⇗, Implementation: C
• GitHub/hoedown: hoedown ⇗ Implementation: C v3.0.7 2015.12.03
• Markingbird Swift port of MarkdownSharp. No longer actively maintained.
• Pandoc
  • Pandoc User’s Guide ⇗
  • GitHub: pandoc ⇗ Implementation: Haskell
• Perfect-Markdown Swift wrapper which directly builds on libupskirt which was forked from sundown.

CommonMark

Note: CommonMark Spec ⇗ does not mention any support for LaTeX math.

• CommonMark: home ⇗, github ⇗ 0.28.3 2017.10, brew: cmark | commonmark
• Github/github: cmark ⇗ GitHub Flavored Markdown, extended CommonMark , brew: cmark-cfm v0.28.3.gfm.20
  • GitHub Flavored Markdown Spec Adds tables, task lists and autolinks. Does not add LaTeX math.
• brew conflict: cmark|commonmark and cmark-cfm, both install cmark.h
• Github/iwasrobbed: Down ⇗ Swift wrapper for reference cmark C. does not use Swift Package Manager.
• Github/Pyroh: SwiftMark ⇗ Swift framework which wraps libcmark. beta 2016.01.26.
• Github/calebkleveter: SwiftMark ⇗, guide ⇗, site ⇗ pure Swift. Early development. Roadmap to support GFM (GitHub Flavored Markdown) features.

MultiMarkdown

• MultiMarkdown markdown
• GitHub/fletcher: MultiMarkdown-5
• GitHub/fletcher: MultiMarkdown-6 Implementation: C
• Homebrew installs multimarkdown with binary markdown.
  • brew conflict: discount, markdown and multimarkdown install markdown binaries.
  • brew conflict: mtools (MSDOS file manipulation) … both install mmd binaries.