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"); // or output Stream

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

ImagesBaseUri 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()
{
    SkipImages = true
};
converter.ToDocx(markdown, "output.docx");

Note: base64 images and RAW html blocks are not supported by the converter.
In addition, WEBP, AVIF and JPEG-XL images are not supported in DOCX (the Open XML specification supports JPEG, GIF, PNG, BMP, SVG, as well as other formats typically not used by Markdown or browsers).
You can install the DocSharp.ImageSharp package and set the ImageConverter property in order to convert other image formats:

var converter = new MarkdownConverter()
{
    ImageConverter = new ImageSharpConverter()
};
converter.ToDocx(markdown, "output.docx");

This will use the ImageSharp library to convert WebP images; at this time ImageSharp does not support AVIF and JXL.
Please note that while the DocSharp.SystemDrawing package exists for other converters, it is not useful in this case as System.Drawing.Common does not support these formats unless specific codecs are installed on the system.

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.
You can also get a XDocument or string in the FlatOPC format using the ToFlatOpc() or ToFlatOpcString() methods.

Get DOCX bytes

To get the DOCX bytes directly use the ToDocxBytes() function instead of ToDocx():

byte[] bytes = converter.ToDocxBytes(markdown);

Set output document type

All functions converting to DOCX accept an additional argument to specify the Open XML document type. It is set to WordprocessingDocumentType.Document by default, but can be changed to Template or Macro-enabled Document if desired:

converter.ToDocx(markdown, "output.dotx", WordprocessingDocumentType.Template);

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.

Convert Markdown to RTF

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(filePath), // or a custom folder path or http(s) URL
    ImageConverter = new ImageSharpConverter() // or SystemDrawingConverter
};
converter.ToRtf(markdown, "output.rtf"); // or output Stream

MarkdownSource, ImagesBaseUri, ImageConverter and SkipImages work in the same way explained above for DOCX, except that GIF images are also not supported in RTF and need conversion using ImageSharp or System.Drawing (ImageSharp is recommended as it also supports WebP and is cross-platform).

Convert to RTF string

To get the RTF string directly use the ToRtfString() function instead of ToRtf():

string rtf = converter.ToRtfString(markdown);

Customize Markdown to RTF conversion

You can pass an additional MarkdownToRtfSettings object to the ToRtf (or ToRtfString) method:

var markdown = MarkdownSource.FromFile("markdown.md");
var converter = new MarkdownConverter()
{
    ImagesBaseUri = Path.GetDirectoryName("markdown.md"),
    ImageConverter = new ImageSharpConverter()
};
converter.ToRtf(markdown, "output.rtf", new MarkdownToRtfSettings() 
{
    DefaultFont = "Times New Roman",
    CodeFont = "Cascadia Mono"
});

The MarkdownToRtfSettings class contains the following properties which can be customized:

• DefaultFont (default: Arial)
• DefaultFontSize (default: 12)
• DefaultTextColor (default: black)
• HeadingFonts (dictionary; default is Arial)
• HeadingFontSizes (dictionary; default are 36-24-20-16-14-12)
• HeadingIsBold (dictionary; default is true)
• HeadingColors (dictionary; default is black)
• QuoteFont (default: Arial)
• QuoteFontSize (default: 12)
• QuoteFontColor (default: #767171)
• QuoteIndent (in points; default is 10)
• QuoteBorderWidth (left border width in points; default is 2.25)
• QuoteBorderColor (default: #A6A6A6)
• QuoteBackgroundColor (default: no background color)
• CodeFont (default: Courier New)
• CodeFontColor (default: black)
• CodeFontSize (default: 12)
• CodeBorderColor (default: #808080)
• CodeBorderWidth (outside border width in points; default is 0.5)
• CodeBackgroundColor (default: #D9D9D9)
• ParagraphSpaceAfter (in points; default is 8)
• LineSpacing (in lines, default is 1.15)
• LinkColor (default: blue)