004.55 Markdown CLI Evaluation

| Objectives | Process | Observations | Resources |

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

:TODO: add cmark-gfm. add SwiftMark.

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.

Process ▴

1. Install "discount" (which installs as markdown), hoedown, and pandoc as command line tools.
2. Edit soure markdown file md_evaluation.md
3. 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 markdown and MultiMarkdown markdown have the same command name. 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.

Note: brew cmark and cmark-gfm conflict because both install a cmark.h header.

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 \(, \[ 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.

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">.

MacDown

• Hang. If MacDown Preference Update preview automatically as you type is enabled, then editing the md_evaluation.md document may cause MacDown to hang. Likely related to html render, not markdown highlighting. Maybe related to time to render a document which requires a significant amount of JavaScript to run including the remotely loaded MathJax libraries. see issue 807 ⇗. Workaround: disable Update preview automatically as you type.

Resources ▴

DaringFireball: markdown ⇗ Implementation: Perl
Discount markdown ⇗ Implementation: C
GitHub/hoedown: hoedown ⇗ Implementation: C
GitHub/fletcher: MultiMarkdown-5
GitHub/fletcher: MultiMarkdown-6
GitHub: pandoc ⇗ Implementation: Haskell
MultiMarkdown markdown Implementation: C
Pandoc User’s Guide ⇗

Github/github: cmark ⇗ aka cmark-cfm
CommonMark: home ⇗