Convert Markdown documents

Convert Markdown to DOCX

1. Install the DocSharp.Markdown package from NuGet. This will also install the Markdig library.

2. Use the following code to get started:

using DocSharp.Markdown;
// ...
var markdown = MarkdownSource.FromFile("markdown.md");
var converter = new MarkdownConverter()
{
    ImagesBaseUri = Path.GetDirectoryName("markdown.md")
};
converter.ToDocx(markdown, "output.docx");

Alternatively you can use FromStream or FromMarkdownString to build a Markdown source.
A Markdig MarkdownDocument object also implicitly converts to a MarkdownSource.

ImageBaseUri can be an absolute local folder path or an http(s) URL, allowing to process e.g. images stored on GitHub. The relative URI often found in Markdown documents such as as ./image1.jpg will be combined with the base URI.
If this property is not set, only images which are already expressed as absolute URIs (such as C:\image.jpg or https://www.example.com/image.jpg) will be processed.
To completely prevent the converter from trying to download online images or access local images, set the SkipImages property to true:

var markdown = MarkdownSource.FromFile(filePath);
var converter = new MarkdownConverter()
{
    SkipImage = true
};
converter.ToDocx(markdown, "output.docx");

Please note that WEBP, AVIF and JPEG-XL images are not supported in DOCX and will be ignored. Supported images include JPEG, GIF, PNG, BMP, SVG, as well as other formats typically not used by Markdown or browsers. Base64 images are also not supported by the converter.

Get a WordprocessingDocument object

To retrieve an Open XML SDK WordprocessingDocument object that can be further edited, you can use the ToWordprocessingDocument function:

var markdown = MarkdownSource.FromFile(filePath);
var converter = new MarkdownConverter()
{
    ImagesBaseUri = Path.GetDirectoryName(filePath)
};
WordprocessingDocument doc = converter.ToWordprocessingDocument(markdown, "output.docx");

In this case, the application is responsible for saving and disposing the document object.

Append to existing DOCX document

To append the converted Markdown to an existing document, use the following code:

var markdown = MarkdownSource.FromFile(filePath);
var converter = new MarkdownConverter()
{
    ImagesBaseUri = Path.GetDirectoryName(filePath)
};
converter.ToDocx(markdown, "existing.docx", append: true);

Alternatively, you can use the AppendToDocument method to add markdown to an already created/loaded WordprocessingDocument object that can be further edited:

var markdown = MarkdownSource.FromFile(filePath);
var converter = new MarkdownConverter()
{
    ImagesBaseUri = Path.GetDirectoryName(filePath)
};
converter.AppendToDocument(markdown, wpDocument);

Customize styles

Default styles required for Markdown to DOCX conversion are automatically added to the document unless a style with the same name is already defined.

Therefore to override styles you need to:

1. Use the Open XML SDK or a word processor (such as Microsoft Word or LibreOffice) to create or load a document and add one or more of the following styles:

   • Unknown formatting: "MDNormal"
   • Paragraph: "MDParagraphTextBody"
   • Code block: "MDPreformattedText"
   • Inline code: "CodeInline"
   • Quote: "MDQuotations"
   • Horizontal line: "MDHorizontalLine"
   • Ordered list: "MDListNumber"
   • Ordered list item: "MDListNumberItem"
   • Bulleted list: "MDListBullet"
   • Bulleted list item: "MDListBulletItem"
   • Hyperlink: "MDHyperlink"
   • Title: "Title"
   • Headings: "MDHeading1", "MDHeading2", "MDHeading3", "MDHeading4", "MDHeading5", "MDHeading6"

2. Append the converted Markdown to the document as described above:

converter.AppendToDocument(markdown, wpDocument);

or

converter.ToDocx(markdown, "template.docx", append: true);

These methods will preserve the document content, if any. If no extra content is desired, just use a blank document with one or more of the styles listed above.