Word to Markdown Conversion

The OfficeIMO.Word.Markdown package provides bidirectional conversion between Word documents and Markdown. It builds on OfficeIMO.Word , OfficeIMO.Markdown , and OfficeIMO.Word.Html to handle headings, formatting, tables, lists, images, and more.

Installation

dotnet add package OfficeIMO.Word.Markdown

This package depends on OfficeIMO.Word , OfficeIMO.Word.Html , OfficeIMO.Markdown , and OfficeIMO.Markdown.Html .

Word to Markdown

Convert to Markdown String

using OfficeIMO.Word;
using OfficeIMO.Word.Markdown;

using var document = WordDocument.Load("report.docx");

string markdown = document.ToMarkdown();
Console.WriteLine(markdown);

Async Conversion

string markdown = await document.ToMarkdownAsync();

Convert to Markdown AST

Get a typed MarkdownDoc AST for further processing:

using OfficeIMO.Word;
using OfficeIMO.Word.Markdown;
using OfficeIMO.Markdown;

using var document = WordDocument.Load("report.docx");
MarkdownDoc markdownDoc = document.ToMarkdownDocument();

// Inspect the structure
foreach (var heading in markdownDoc.DescendantHeadings()) {
    Console.WriteLine($"H{heading.Level}: {heading.Text}");
}

// Render to string
var output = markdownDoc.ToMarkdown();

Save as Markdown File

document.SaveAsMarkdown("report.md");

// Async version
await document.SaveAsMarkdownAsync("report.md");

Save to a Stream

using var stream = new MemoryStream();
document.SaveAsMarkdown(stream);

Conversion Options

using OfficeIMO.Word;
using OfficeIMO.Word.Markdown;

using var document = WordDocument.Load("report.docx");

var options = new WordToMarkdownOptions {
    EnableUnderline = true,
    EnableHighlight = true
};

string markdown = document.ToMarkdown(options);

Markdown to Word

Create a Word Document from Markdown String

using OfficeIMO.Word.Markdown;

string markdown = @"
# Project Report

## Summary

This report covers **Q4 performance**.

| Metric | Value |
|--------|-------|
| Revenue | $1.2M |
| Users | 5,000 |

## Conclusion

Overall positive results.
";

using var document = markdown.LoadFromMarkdown();
document.Save("from-markdown.docx");

Create from a Markdown File

using var document = WordMarkdownConverterExtensions.LoadFromMarkdown(
    "README.md"
);
document.Save("readme.docx");

Create from a Stream

using var stream = File.OpenRead("document.md");
using var document = stream.LoadFromMarkdown();
document.Save("output.docx");

Async Markdown to Word

using var document = await "README.md".LoadFromMarkdownAsync();
document.Save("readme.docx");

Create from a MarkdownDoc AST

If you have already parsed or built a MarkdownDoc , convert it directly:

using OfficeIMO.Markdown;

var md = MarkdownDoc.Create()
    .H1("Generated Report")
    .P("Created programmatically.")
    .Table(t => t
        .Headers("Item", "Count")
        .Row("Widgets", "42")
        .Row("Gadgets", "17")
    );

using var document = md.ToWordDocument();
document.Save("generated.docx");

Markdown to Word Options

var options = new MarkdownToWordOptions {
    // Configure default styles, fonts, etc.
};

using var document = markdown.LoadFromMarkdown(options);

HTML via Markdown

Convert Word to HTML by going through the Markdown pipeline. This can produce cleaner HTML than the direct Word-to-HTML converter for simple documents:

using var document = WordDocument.Load("report.docx");

// Word -> Markdown -> HTML
string html = document.ToHtmlViaMarkdown();

For an HTML fragment (no <html> , <head> , <body> wrapper):

string fragment = document.ToHtmlFragmentViaMarkdown();

Save the HTML output to a file:

document.SaveAsHtmlViaMarkdown("report.html");

HTML to Word via Markdown

Convert HTML to Word by first converting to Markdown, then to Word:

string html = "<h1>Hello</h1><p>World</p>";

using var document = html.LoadFromHtmlViaMarkdown();
document.Save("from-html-via-md.docx");

From a stream:

using var htmlStream = File.OpenRead("page.html");
using var document = htmlStream.LoadFromHtmlViaMarkdown();
document.Save("output.docx");

Element Mapping

The converter maps between Word and Markdown elements:

Word Element	Markdown Element
Heading1--Heading6 styles	`#` through `######`
Normal paragraph	Plain paragraph text
Bold run	`bold`
Italic run	`italic`
Bold + Italic run	`*bold italic*`
Strikethrough	`~~strikethrough~~`
Inline code style	`code`
Hyperlink	`[text](url)`
Table	GFM pipe table
Bulleted list	`- item`
Numbered list	`1. item`
Image	`![alt](path)`
Horizontal rule	`---`
Block quote style	`> text`

Round-Trip Fidelity

While the converters handle the most common elements, some formatting may be lost during round-trip conversion (Word -> Markdown -> Word or vice versa). Complex features like nested tables, custom table styles, SmartArt, and embedded OLE objects do not have Markdown equivalents and will be simplified or omitted.