Universal.OpenXml.Markdown 1.0.0

Universal.OpenXml.Markdown

A powerful .NET library that converts Markdown content directly into Microsoft Word OpenXML documents. Built on top of the Open XML SDK and Markdig, this library provides seamless integration between Markdown and Word document generation with support for all common Markdown elements including tables, lists, code blocks, and formatting.

Features

• Complete Markdown Support - Headings, paragraphs, lists, tables, code blocks, quotes, links, emphasis, and horizontal rules
• Smart List Integration - Automatically uses existing document bullet/numbering styles or creates Word-compatible defaults
• Table Rendering - Full table support with proper borders, headers, and cell formatting
• Extensible Architecture - Virtual methods allow customization of rendering behavior
• Template-Friendly - Works seamlessly with existing Word templates and styles
• Standards Compliant - Generates valid OpenXML that opens perfectly in Microsoft Word

Quick Start

Basic Usage with Extension Methods

using Universal.OpenXml.Markdown;
using DocumentFormat.OpenXml.Packaging;

// Render to main document body
using var doc = WordprocessingDocument.Create("output.docx", WordprocessingDocumentType.Document);
doc.AddMainDocumentPart().Document = new Document(new Body());

string markdown = @"
# My Document
This is a **bold** statement with *italic* text.

- Bullet item 1
- Bullet item 2

1. Numbered item
2. Another item

| Name | Age | City |
|------|-----|------|
| John | 30  | NYC  |
| Jane | 25  | LA   |
";

doc.RenderMarkdown(markdown);
doc.Save();

Using with Existing Templates

// Work with existing Word templates
using var template = WordprocessingDocument.CreateFromTemplate("template.docx");
var contentControl = template.MainDocumentPart.Document.Body
    .GetElementByTag("Content"); // Your custom content control

template.RenderMarkdown(contentControl, markdownContent);
template.SaveAs("output.docx");

Advanced Usage with Custom Renderer

public class CustomMarkdownRenderer : MarkdownRenderer
{
    protected override Paragraph RenderHeading(HeadingBlock heading)
    {
        var paragraph = base.RenderHeading(heading);
        
        // Add custom styling to headings
        if (heading.Level == 1)
        {
            // Custom H1 formatting
            var props = paragraph.ParagraphProperties;
            props.ParagraphStyleId.Val = "CustomHeading1";
        }
        
        return paragraph;
    }
    
    protected override Run RenderInlineCode(CodeInline code)
    {
        var run = base.RenderInlineCode(code);
        
        // Custom code formatting
        var props = run.RunProperties;
        props.Shading.Fill = "FFEB3B"; // Yellow background
        
        return run;
    }
}

// Use custom renderer
var renderer = new CustomMarkdownRenderer();
using var doc = WordprocessingDocument.Create("custom.docx", WordprocessingDocumentType.Document);
renderer.Render(doc, doc.MainDocumentPart.Document.Body, markdown);

Supported Markdown Elements

Smart List Handling

The library intelligently handles list formatting:

1. Existing Styles First - Automatically detects and uses existing bullet/numbering definitions in your document
2. Word-Compatible Defaults - Creates Word-standard list styles when none exist
3. Multi-level Support - Full 9-level hierarchy matching Word's default patterns
4. Proper Indentation - Correct hanging indents and spacing

Table Features

Tables are rendered with full Word compatibility:

• Header Detection - First row automatically styled as table header
• Border Support - Complete table and cell borders
• Header Styling - Bold text and gray background for headers
• Cell Content - Supports all Markdown formatting within cells
• Auto-sizing - Tables automatically adjust to content width

API Reference

MarkdownRenderer Class

The core class for converting Markdown to OpenXML.

Constructors

// Default constructor with standard Markdig pipeline
public MarkdownRenderer()

// Custom constructor with specific Markdig pipeline
public MarkdownRenderer(MarkdownPipeline markdownPipeline)

Main Methods

// Render markdown into specified OpenXML element
public void Render(WordprocessingDocument document, OpenXmlElement container, string markdown)

Virtual Methods for Customization

protected virtual IEnumerable<OpenXmlElement> RenderBlock(Block block)
protected virtual Paragraph RenderHeading(HeadingBlock heading)
protected virtual Paragraph RenderParagraph(ParagraphBlock paragraph)
protected virtual IEnumerable<OpenXmlElement> RenderList(ListBlock list)
protected virtual Table RenderTable(Markdig.Extensions.Tables.Table table)
protected virtual IEnumerable<OpenXmlElement> RenderQuoteBlock(QuoteBlock quote)
protected virtual IEnumerable<Run> RenderEmphasis(EmphasisInline emphasis)
protected virtual IEnumerable<Run> RenderHyperlink(LinkInline link)
protected virtual Run RenderInlineCode(CodeInline code)
protected virtual Paragraph RenderCodeBlock(CodeBlock codeBlock)
protected virtual Paragraph RenderHorizontalRule()

Extension Methods

Convenient extension methods for WordprocessingDocument:

// Render to main document body
public static void RenderMarkdown(this WordprocessingDocument document, string markdown)

// Render to specific element
public static void RenderMarkdown(this WordprocessingDocument document, OpenXmlElement element, string markdown)