Migrating to the new engine

Version 2.0.0 of the Markdown Processor introduces a new engine for the CommonMark dialect, that now follows the CommonMark 0.31.2 specification exactly, and two new dialects on the same engine: GFM (GitHub Flavored Markdown 0.29) and GitHub (GFM plus math, alerts and mermaid, as github.com), which becomes the default dialect.

The DaringFireball and TxtMark dialects are unchanged: their output is checked by snapshot tests and stays exactly the same.

The default dialect

TMarkdownProcessor.CreateDialect now has a parameter with a default value, DefaultMarkdownDialect = mdGitHub: CreateDialect without arguments creates a GitHub processor. Existing calls that pass a dialect are unchanged.

mdGFM and mdGitHub are appended at the end of TMarkdownProcessorDialect, so the ordinal values of the existing dialects do not change (0 DaringFireball, 1 CommonMark, 2 TxtMark): settings saved as integers keep working. A case over the dialects may need new branches.

MarkDownToHTML.exe now uses the GitHub dialect when -dialect: is not given (it used CommonMark). Its pages contain no scripts, so it writes math formulas as images (as before) and mermaid diagrams as their source.

What changes for the CommonMark dialect

1. Tables, task lists and strikethrough are not part of CommonMark: they need the GFM or GitHub dialect, or the extensions mexTables, mexTaskLists, mexStrikethrough.
2. The non-standard syntax is off by default: smart typography, ~sub~, ^sup^, ++ins++, ==mark==, # Title {#id}, [[wiki links]] and $ math must be enabled through Config.Extensions.
3. Math formulas are written by default as markup for KaTeX or MathJax (<span class="math">, <div class="math">) instead of an image from latex.codecogs.com. To get the images back set Config.MathRendering := mmrCodeCogsImage.
4. Safe mode (AllowUnsafe = False, the default) omits raw HTML, writing <!-- raw HTML omitted -->, instead of escaping it, and empties the javascript:, vbscript:, file: and data: links.
5. The HTML follows the specification: tables with <thead> and <tbody>, <br />, <hr />, <img ... />, no paragraphs inside the items of tight lists.
6. Smart typography (mexSmartTypography) writes Unicode characters (–, —, …, ©, “ ”) instead of HTML entities (–...).
7. A custom TDecorator affects only the legacy dialects: to change the HTML of the new engine derive from TMarkdownHtmlRenderer, which has one virtual method per element.

Getting the previous features back

The features of the old CommonMark dialect, on the new engine:

md := TMarkdownProcessor.CreateDialect(mdGitHub); // tables, task lists, ~~del~~, autolinks, math
md.Config.Extensions := md.Config.Extensions + [
  mexSubscript, mexSuperscript, mexInsert, mexMark,
  mexSmartTypography, mexHeadingAttributes, mexWikiLinks];
md.Config.MathRendering := mmrCodeCogsImage;    // math as images, as before

With both mexStrikethrough and mexSubscript, ~~x~~ is strikethrough and ~x~ is subscript.

Showing math and diagrams

Viewer	Settings	The page must load
With JavaScript (e.g. WebView2)	mmrMarkup (default), mexMermaid on	KaTeX or MathJax, mermaid.js
Without JavaScript (e.g. HTMLViewer)	mmrCodeCogsImage; mermaid diagrams show their source	nothing (math images need the network)

The Config.codeBlockEmitter hook, when assigned, still receives every code block, mermaid diagrams included, with its whole info string: an application can use it to render diagrams in its own way.

See Markdown Processor for the complete description of the library.