Markdown

A CommonMark 0.31.2 reader and writer, with GitHub's tables, strikethrough and task lists on by default. Markdown converts to Word and PDF with real styles, and Word documents export to clean Markdown.

Read and write

using DocWright;
using DocWright.Core.Diagnostics;
using DocWright.Core.Formats;
using DocWright.Dom;
using DocWright.Formats.Markdown;

// Markdown in (name the format: its signature is weak), Markdown out with chosen style.
using WordDocument article = converter.Load(File.OpenRead("article.md"), FormatDetection.Markdown);

var markdown = new MarkdownWriter(new MarkdownWriteOptions
{
    Flavor = MarkdownFlavor.GitHubFlavored,
    BulletStyle = MarkdownBulletStyle.Asterisk,
    NewLine = "\n",
});

using (FileStream output = File.Create("article-roundtrip.md"))
{
    markdown.Write(article, output, new DocumentWriteOptions(), NullConversionDiagnostics.Instance);
}

The source, article.md, round-trips to:

# DocWright Markdown corpus

This document is a Markdown *source* in the visual corpus. It exists so that the fidelity pipeline observes the Markdown reader at all: before Phase 31 every corpus document was a DOCX, so four format readers shipped with no rendered coverage whatsoever.

## What this document exercises

The reader's block mapping is the subject: ATX headings at three levels, paragraphs carrying **strong** and *emphasised* runs, a `code span`, an [inline link](https://example.invalid/docs), a block quote, a fenced code block, a bulleted list and an ordered list.

> A block quote becomes paragraphs carrying the Quote style, indented on both sides and set in italics. Nesting is flattened to one level, which is why this quote has only one, and the line above ends in a soft break rather than a paragraph.

### Headings map to styles, not to sizes

Tip

Name the format when loading. Auto-detection only recognizes Markdown when the first 4 KB contain a Markdown construct (a heading, list, fence, quote or table) at the start of a line. A file of plain prose is not detected. Use FormatDetection.Markdown.

Headings become styles

# Heading becomes a paragraph in the Heading 1 style, not just large bold text. Code blocks, quotes and inline code likewise get named styles (HTMLPreformatted, Quote, HTMLCode). They render as themselves, appear in Word's navigation pane, and export back to the same Markdown.

Writer options

MarkdownWriteOptions	Default	Choices
Flavor	GitHubFlavored	CommonMark for strict output. Pipe tables then become paragraphs, with a diagnostic.
BulletStyle	Hyphen	Asterisk, Plus
EmphasisStyle	Asterisk	Underscore
TableStyle	Pipe	Paragraphs
UseAtxHeadings	true	false writes setext headings (===) for levels 1 and 2.
EmbedImagesAsDataUris	false	Write image bytes into the file instead of references.
NewLine	"\n"	"\n" or "\r\n".

Reader behaviour

• Images are not fetched. ![alt](photo.png) becomes its alt text, with a diagnostic. data: URI images are imported.
• Raw HTML stays visible as text, reported as DXP2002, rather than silently disappearing. Set KeepRawHtmlAsText = false to drop it.
• YAML front matter (a leading --- block) is skipped and reported.
• MarkdownReadOptions.Flavor = MarkdownFlavor.CommonMark treats | tables and ~~strike~~ as plain text, as the specification does.

What survives

Markdown has no vocabulary for fonts, colours, sizes, alignment, page setup, headers, footnotes or merged cells. When you export a Word document, those are dropped and reported. The reader is checked against the CommonMark specification's 652 examples. The ones that differ are almost all raw HTML, which a Word document has nowhere to put.