Rendering the Markdown

edit

The Markdown that the converter writes follows CommonMark, plus four common extensions: pipe tables, task lists, strikethrough (~~) and definition lists. A renderer that only implements CommonMark shows these as text. With Meziantou.Framework.Markdown, enable them in the parse options:

var markdown = HtmlToMarkdown.Convert("<table><tr><th>Name</th><th>Price</th></tr><tr><td>Apple</td><td><del>1.50</del> 1.20</td></tr></table>");
Assert.Equal("""
    | Name | Price |
    | --- | --- |
    | Apple | ~~1.50~~ 1.20 |
    """, markdown);

// Pipe tables and strikethrough are extensions of CommonMark: enable them to render the Markdown
var html = MarkdownConverter.ToHtml(markdown, new MarkdownParseOptions { Extensions = MarkdownExtensions.Advanced });
Assert.Contains("<td><del>1.50</del> 1.20</td>", html, StringComparison.Ordinal);

MarkdownExtensions.Advanced enables all four, with other extensions: see Extensions to enable them one by one.

The converter writesExtension of Meziantou.Framework.Markdown
Pipe tables, from tablePipeTables
Task lists, from checkboxesTaskLists
~~, from del, s and strikeStrikethrough
Definition lists, from dlDefinitionLists
Shortcodes, with EmojiShortcodeModeEmoji, not enabled by Advanced

Round trip

Converting HTML to Markdown and rendering it again usually gives an equivalent HTML for the converted elements: the same structure and the same text. It does not give the same markup:

  • the attributes that Markdown cannot write (class, id, style...) are lost, and the containers (div, section...) are replaced by their content;
  • the whitespace is collapsed, outside of the code blocks;
  • a list can change between tight and loose, so its items gain or lose their p elements;
  • the renderer writes its own markup, such as the thead and tbody of a table, or the alignment of its cells.

The unknown elements written as raw HTML are rendered again as they are, when the renderer allows raw HTML. Read Security before you render Markdown that comes from untrusted HTML.