Markdown to Word Conversion

24 Jul 202615 minutes to read

Markdown is a lightweight markup language that adds formatting elements to plain text documents. The .NET Word (DocIO) library supports converting Markdown files to Word documents, which mostly follows the CommonMark specification and GitHub-flavored syntax.

To quickly start converting a Markdown file to a Word document, check out this video:

Assemblies and NuGet packages required

Refer to the following links for assemblies and NuGet packages required based on platforms to convert a Markdown file to a Word document using the .NET Word Library (DocIO).

Convert Markdown to Word document

Convert an existing markdown file to a Word document (DOC, DOCX, or RTF) using the .NET Word (DocIO) library.

The following code example shows how to convert a Markdown file to a Word document. Add the required using directives to your source file:

using System.IO;
using Syncfusion.DocIO;
using Syncfusion.DocIO.DLS;

NOTE

Refer to the appropriate tabs in the code snippets section: C# [Cross-platform] for ASP.NET Core, Blazor, Xamarin, UWP, .NET MAUI, and WinUI; C# [Windows-specific] for WinForms and WPF; VB.NET [Windows-specific] for VB.NET applications.

C# [Cross-platform]
C# [Windows-specific]
VB.NET [Windows-specific]
// Open an existing Markdown file.
using (WordDocument document = new WordDocument(Path.GetFullPath(@"Data/Input.md")))
{
    // Save as a Word document.
    document.Save(Path.GetFullPath(@"Output/MarkdownToWord.docx"), FormatType.Docx);
}
//Open an existing Markdown file.
using (WordDocument document = new WordDocument("Input.md", FormatType.Markdown))
{
    //Save as a Word document.
    document.Save("MarkdownToWord.docx", FormatType.Docx);
}
'Open an existing Markdown file.
Using document As WordDocument = New WordDocument("Input.md", FormatType.Markdown)
    'Save as a Word document.
    document.Save("MarkdownToWord.docx", FormatType.Docx)
End Using

You can download a complete working sample from GitHub.

TIPS

You can also save the markdown file as HTML, PDF, and Image.

NOTE

In Markdown to Word conversion, SVG or invalid images are replaced with a red “X” image instead of the original image.

Markdown Import Settings

When opening an existing Markdown document, the .NET Word (DocIO) library provides custom import settings through the MdImportSettings property. This allows you to customize how the Markdown content is parsed and imported.

The following properties are available on MdImportSettings:

Property	Description
`ImageNodeVisited`	An event raised for each image encountered while importing. Use it to load image data from a custom source.
`Encoding`	The character encoding used to read the Markdown file. Defaults to `Encoding.UTF8`.

Customize image data

The .NET Word (DocIO) library provides an ImageNodeVisited event that customizes image data while importing a Markdown file. Handle this event to load image data from a custom source.

The ImageNodeVisited event provides an MdImageNodeVisitedEventArgs object with the following members:

Uri — the image source declared in the Markdown (file name, relative path, or URL).
ImageStream — the stream to populate. The library reads from this stream when inserting the image into the Word document.

The following code example shows how to load image data based on the image source path when importing the Markdown files.

C# [Cross-platform]
C# [Windows-specific]
VB.NET [Windows-specific]
//Create a Word document instance.
using (WordDocument document = new WordDocument())
{
    // Hook the event to customize the image while importing Markdown.
    document.MdImportSettings.ImageNodeVisited += MdImportSettings_ImageNodeVisited;
    // Open the Markdown file.
    document.Open(Path.GetFullPath("Data/Input.md"));
    // Save as a Word document.
    document.Save(Path.GetFullPath(@"Output/Sample.docx"));
}
//Create a Word document instance.
using (WordDocument document = new WordDocument())
{
    //Hook the event to customize the image while importing Markdown.
    document.MdImportSettings.ImageNodeVisited += MdImportSettings_ImageNodeVisited;
    //Open the Markdown file.
    document.Open("Input.md");
    //Save as a Word document.
    document.Save("Sample.docx");
}
'Create a Word document instance.
Using document As WordDocument = New WordDocument()
    'Hook the event to customize the image while importing Markdown.
    document.MdImportSettings.ImageNodeVisited += MdImportSettings_ImageNodeVisited
    'Open the Markdown file.
    document.Open("Input.md")
    'Save as a Word document.
    document.Save("Sample.docx")
End Using

The following code examples show the event handler to customize the image based on the source path.

C# [Cross-platform]
C# [Windows-specific]
VB.NET [Windows-specific]
private static void MdImportSettings_ImageNodeVisited(object sender, Syncfusion.Office.Markdown.MdImageNodeVisitedEventArgs args)
{
    //Set the image stream based on the image name from the input Markdown.
    if (args.Uri == "Image_1.png")
        args.ImageStream = new FileStream("Image_1.png", FileMode.Open);
    else if (args.Uri == "Image_2.png")
        args.ImageStream = new FileStream("Image_2.png", FileMode.Open);
    //Retrieve the image from the website and use it.
    else if (args.Uri.StartsWith("https://"))
    {
        //Download the image as a stream.
        using (HttpClient client = new HttpClient())
        {
            byte[] image = client.GetByteArrayAsync(args.Uri).GetAwaiter().GetResult();
            args.ImageStream = new MemoryStream(image);
        }
    }
}
private static void MdImportSettings_ImageNodeVisited(object sender, Syncfusion.Office.Markdown.MdImageNodeVisitedEventArgs args)
{
    //Set the image stream based on the image name from the input Markdown.
    if (args.Uri == "Image_1.png")
        args.ImageStream = new FileStream("Image_1.png", FileMode.Open);
    else if (args.Uri == "Image_2.png")
        args.ImageStream = new FileStream("Image_2.png", FileMode.Open);
    //Retrieve the image from the website and use it.
    else if (args.Uri.StartsWith("https://"))
    {
        //Download the image as a stream.
        using (HttpClient client = new HttpClient())
        {
            byte[] image = client.GetByteArrayAsync(args.Uri).GetAwaiter().GetResult();
            args.ImageStream = new MemoryStream(image);
        }
    }
}
Private Shared Sub MdImportSettings_ImageNodeVisited(ByVal sender As Object, ByVal args As Syncfusion.Office.Markdown.MdImageNodeVisitedEventArgs)
    'Set the image stream based on the image name from the input Markdown.
    If args.Uri Is "Image_1.png" Then
        args.ImageStream = New FileStream("Image_1.png", FileMode.Open)
    ElseIf args.Uri Is "Image_2.png" Then
        args.ImageStream = New FileStream("Image_2.png", FileMode.Open)
    'Retrieve the image from the website and use it.
    ElseIf args.Uri.StartsWith("https://") Then
        'Download the image as a stream.
        Using client As New HttpClient()
            Dim image As Byte() = client.GetByteArrayAsync(args.Uri).GetAwaiter().GetResult()
            args.ImageStream = New MemoryStream(image)
        End Using
    End If
End Sub

NOTE

Hook the event handler before opening the Markdown file, as shown in the previous code example. Stream instances assigned to args.ImageStream are not disposed by DocIO; dispose of them yourself when you no longer need the image data.

You can download a complete working sample from GitHub.

Encoding

The .NET Word (DocIO) library provides an Encoding property to specify the character encoding to use when opening a Markdown file. This property is useful when you need to open Markdown files that are saved with specific character encodings such as UTF-8, UTF-16, or ASCII. The default value is Encoding.UTF8.

The following code example shows how to open a Markdown file with a specific encoding.

C# [Cross-platform]
C# [Windows-specific]
VB.NET [Windows-specific]
//Create a Word document instance.
using (WordDocument document = new WordDocument())
{
    //Set the encoding for the Markdown file.
    document.MdImportSettings.Encoding = System.Text.Encoding.UTF8;
    //Open the Markdown file.
    document.Open(Path.GetFullPath("Data/Input.md"));
    //Save as a Word document.
    document.Save(Path.GetFullPath(@"Output/Output.docx"), FormatType.Docx);
}
//Create a Word document instance.
using (WordDocument document = new WordDocument())
{
    //Set the encoding for the Markdown file.
    document.MdImportSettings.Encoding = System.Text.Encoding.UTF8;
    //Open the Markdown file.
    document.Open("Input.md");
    //Save as a Word document.
    document.Save("Output.docx", FormatType.Docx);
}
'Create a Word document instance.
Using document As WordDocument = New WordDocument()
    'Set the encoding for the Markdown file.
    document.MdImportSettings.Encoding = System.Text.Encoding.UTF8
    'Open the Markdown file.
    document.Open("Input.md")
    'Save as a Word document.
    document.Save("Output.docx", FormatType.Docx)
End Using

NOTE

Provide the encoding value before opening the Markdown file, as shown in the above code example.

Supported Markdown Syntax

Element	Syntax	Description
Bold	Sample content for bold text.	For bold, add ** to the front and back of the text.
Italic	Sample content for Italic text.	For italic, add * to the front and back of the text.
Bold and Italics	Sample content for *bold and Italic text*.	For bold and italics, add *** to the front and back of the text.
Strikethrough	Sample content for ~~strike through text~~.	For strikethrough, add ~~ to the front and back of the text.
Subscript (HTML)	<sub>Subscript text</sub>	For subscript, add <sub> to the front and </sub> to the back of the text.
Superscript (HTML)	<sup>Superscript text</sup>	For superscript, add <sup> to the front and </sup> to the back of the text.
Heading 1	#Heading 1 content	For heading 1, add # to the start of the line.
Heading 2	##Heading 2 content	For heading 2, add ## to the start of the line.
Heading 3	###Heading 3 content	For heading 3, add ### to the start of the line.
Heading 4	####Heading 4 content	For heading 4, add #### to the start of the line.
Heading 5	#####Heading 5 content	For heading 5, add ##### to the start of the line.
Heading 6	######Heading 6 content	For heading 6, add ###### to the start of the line.
Block quotes	>Block quotes text	For block quotes, add > to the start of the line.
Code span	`Code span text`	For a code span, add ` to the front and back of the text.
Indented code block	4 spaces	For an indented code block, add 4 spaces at the beginning of the line.
Fenced code block	``` Multi line code text Multi line code text ```	For a fenced code block, add ``` on a new line before and after the content.
Ordered List	1. First 2. Second	For an ordered list, precede the text with a number followed by a dot and a space (for example, `1.` ).
Unordered List	- First - second	For an unordered list, precede the text with – (hyphen and space).
Links	Link text without title text: [Link text](URL) Link text with title text: [Link text](URL , “title text”)	For a hyperlink, enclose the link text within brackets [ ], and then enclose the URL as the first parameter and the title as the second parameter within parentheses (). Note: The title text is optional.
Table		Create a table using the pipes and underscores as shown in the syntax to create a 2 x 2 table. You can also set column alignments using the syntax below; the default is left aligned. Right alignment: Center alignment:
Horizontal Line	--- (three hyphen characters)	For a horizontal line, add --- (three hyphens) on a new line.
Image	![Alternate text] (URL path)	For an image, enclose alternative text within brackets [], and then the image URL within parentheses (). If the URL is a base64 string, it will be preserved properly in the Word document. Otherwise, see the [customize image data](#customize-image-data) section to set the image from a stream while opening the Markdown file.
Escape Character	\(any syntax)	Escape any markdown syntax by adding \ as prefix to the syntax. Example: \non-bold text

Online Demo

Explore how to convert the Markdown file to Word document using the .NET Word Library (DocIO) in a live demo here.

Search docs

Ask Syncfusion AI Assistant