Syncfusion AI Assistant

How can I help you?

Word to Markdown Conversion

25 Jun 202623 minutes to read

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

To quickly start converting a Word document to Markdown and vice versa, please 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 Word document to a Markdown file using the .NET Word Library (DocIO).

Convert Word to Markdown

Convert an existing Word document or document that is created from scratch into a Markdown file using the .NET Word (DocIO) library.

The following code example shows how to convert a Word document to a Markdown.

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 Word document.
using (WordDocument document = new WordDocument(Path.GetFullPath(@"Data/Input.docx")))
{
    // Save the document as a Markdown file.
    document.Save(Path.GetFullPath(@"Output/Output.md"));
}
//Open an existing Word document.
using (WordDocument document = new WordDocument("Input.docx", FormatType.Docx))
{
    //Save the document as a Markdown file.
    document.Save("WordtoMd.md", FormatType.Markdown);
}
'Open an existing Word document.
Using document As WordDocument = New WordDocument("Input.docx", FormatType.Docx)
    'Save the document as a Markdown file.
    document.Save("WordtoMd.md", FormatType.Markdown)
End Using

You can download a complete working sample from GitHub.

Design Word document for Markdown conversion

The following table illustrates the supported Markdown elements in Word to Markdown conversion and how to set that Markdown elements in input Word document.

Markdown elements	How to set in Word document
Thematic breaks	Add an horizontal rule.
Headings	Apply heading style for paragraphs. DocIO supports converting 6 levels of headings from a Word document to their equivalent headings' syntax in Markdown. Heading style paragraph. 6 level headings only supported in Markdown.
Indented code block	Paragraph with “IndentedCode” style name.
Fenced code block	Paragraph with “FencedCode” style name.
Block quotes	Paragraph with “Quote” style name
List items	Apply numbered or bulleted list format to paragraphs.
Code span	Set “InlineCode” character style for text.
Emphasis and strong emphasis	Bold and Italic formats for text.
Links	Set hyperlinks in Word document.
Task items	Set checkbox content control as the first item of the paragraph.

Code blocks

The Essential^® DocIO supports two types of code blocks in Word to Markdown conversion.

Indented code block: Set the paragraph style as “IndentedCode.”
Fenced code block: Set the paragraph style as “FencedCode.”

The following code example shows how to create code blocks in a Word document using DocIO.

C# [Cross-platform]
C# [Windows-specific]
VB.NET [Windows-specific]
//Create a new Word document.
using (WordDocument document = new WordDocument())
{
    //Add a new section to the document.
    IWSection section = document.AddSection();
    //Add a new paragraph to the section.
    IWParagraph paragraph = section.AddParagraph();
    //Append text to the paragraph.
    IWTextRange textRange = paragraph.AppendText("Fenced Code");
    //Add a new paragraph to the section.
    paragraph = section.AddParagraph();
    //Create a user-defined style as FencedCode.
    IWParagraphStyle style = document.AddParagraphStyle("FencedCode");
    //Apply FencedCode style for the paragraph.
    paragraph.ApplyStyle("FencedCode");
    //Append text.
    textRange = paragraph.AppendText("class Hello\n{\n\tStatic void Main()\n\t{\n\t\tConsole.WriteLine(\"Fenced Code\")\n\t}\n}");
    //Add a new paragraph and append text to the paragraph.
    section.AddParagraph().AppendText("Indented Code");
    //Add a new paragraph to the section.
    paragraph = section.AddParagraph();
    //Create a user-defined style as IndentedCode.
    style = document.AddParagraphStyle("IndentedCode");
    //Apply IndentedCode style for the paragraph.
    paragraph.ApplyStyle("IndentedCode");
    //Append text.
	textRange = paragraph.AppendText("class Hello\n\t{\n\t\tStatic void Main()\n\t\t{\n\t\t\tConsole.WriteLine(\"Indented Code\")\n\t\t}\n\t}");
	//Save the document as a Markdown file.
	document.Save(Path.GetFullPath(@"Output/Output.md"));
}
//Create a new Word document.
using (WordDocument document = new WordDocument())
{
    //Add a new section to the document.
    IWSection section = document.AddSection();
    //Add a new paragraph to the section.
    IWParagraph paragraph = section.AddParagraph();
    //Append text to the paragraph.
    IWTextRange textRange = paragraph.AppendText("Fenced Code");
    //Add a new paragraph to the section.
    paragraph = section.AddParagraph();
    //Create a user-defined style as FencedCode.
    IWParagraphStyle style = document.AddParagraphStyle("FencedCode");
    //Apply FencedCode style for the paragraph.
    paragraph.ApplyStyle("FencedCode");
    //Append text.
    textRange = paragraph.AppendText("class Hello\n{\n\tStatic void Main()\n\t{\n\t\tConsole.WriteLine(\"Fenced Code\")\n\t}\n}");
    //Add a new paragraph and append text to the paragraph.
    section.AddParagraph().AppendText("Indented Code");
    //Add a new paragraph to the section.
    paragraph = section.AddParagraph();
    //Create a user-defined style as IndentedCode.
    style = document.AddParagraphStyle("IndentedCode");
    //Apply IndentedCode style for the paragraph.
    paragraph.ApplyStyle("IndentedCode");
    //Append text.
    textRange = paragraph.AppendText("class Hello\n\t{\n\t\tStatic void Main()\n\t\t{\n\t\t\tConsole.WriteLine(\"Indented Code\")\n\t\t}\n\t}");
    //Save the document as a Markdown file.
    document.Save("WordtoMd.md", FormatType.Markdown);
}
'Create a new Word document.
Using document As WordDocument = New WordDocument()
    'Add a new section to the document.
    Dim section As IWSection = document.AddSection()
    'Add a new paragraph to the section.
    Dim paragraph As IWParagraph = section.AddParagraph()
    'Append text to the paragraph.
    Dim textRange As IWTextRange = paragraph.AppendText("Fenced Code")
    'Add a new paragraph to the section.
    paragraph = section.AddParagraph()
    'Create a user-defined style as FencedCode.
    Dim style As IWParagraphStyle = document.AddParagraphStyle("FencedCode")
    'Apply FencedCode style for the paragraph.
    paragraph.ApplyStyle("FencedCode")
    'Append text.
    textRange = paragraph.AppendText("class Hello" & vbLf & "{" & vbLf & vbTab & "Static void Main()" & vbLf & vbTab & "{" & vbLf & vbTab & vbTab & "Console.WriteLine(""Fenced Code"")" & vbLf & vbTab & "}" & vbLf & "}")
    'Add a new paragraph and append text to the paragraph.
    section.AddParagraph().AppendText("Indented Code")
    'Add a new paragraph to the section.
    paragraph = section.AddParagraph()
    'Create a user-defined style as IndentedCode.
    style = document.AddParagraphStyle("IndentedCode")
    'Apply IndentedCode style for the paragraph.
    paragraph.ApplyStyle("IndentedCode")
    'Append text.
    textRange = paragraph.AppendText("class Hello" & vbLf & vbTab & "{" & vbLf & vbTab & vbTab & "Static void Main()" & vbLf & vbTab & vbTab & "{" & vbLf & vbTab & vbTab & vbTab & "Console.WriteLine(""Indented Code"")" & vbLf & vbTab & vbTab & "}" & vbLf & vbTab & "}")
    'Save the document as a Markdown file.
    document.Save("WordtoMd.md", FormatType.Markdown)
End Using

You can download a complete working sample from GitHub.

Block quotes

Create block quotes in a Word document by applying the “Quote” paragraph style to the paragraphs.

The following code example shows how to create block quotes in a Word document.

C# [Cross-platform]
C# [Windows-specific]
VB.NET [Windows-specific]
//Create a new Word document.
using (WordDocument document = new WordDocument())
{
    //Add a new section to the document.
    IWSection section = document.AddSection();
    //Create a user-defined style.
    IWParagraphStyle style = document.AddParagraphStyle("Quote");
    //Add a new paragraph to the section.
    IWParagraph paragraph = section.AddParagraph();
    //Apply Quote style to simple hello world text.
    paragraph.ApplyStyle("Quote");
    //Append text.
    IWTextRange textRange = paragraph.AppendText("Hello World");
    //Save the document as a Markdown file.
	document.Save(Path.GetFullPath(@"Output/Output.md"));
}
//Create a new Word document.
using (WordDocument document = new WordDocument())
{
    //Add a new section to the document.
    IWSection section = document.AddSection();
    //Create a user-defined style.
    IWParagraphStyle style = document.AddParagraphStyle("Quote");
    //Add a new paragraph to the section.
    IWParagraph paragraph = section.AddParagraph();
    //Apply Quote style to simple hello world text.
    paragraph.ApplyStyle("Quote");
    //Append text.
    IWTextRange textRange = paragraph.AppendText("Hello World");
    document.Save("WordToMd.md", FormatType.Markdown);
}
'Create a new Word document.
Using document As WordDocument = New WordDocument()
    'Add a new section to the document.
    Dim section As IWSection = document.AddSection()
    'Create a user-defined style.
    Dim style As IWParagraphStyle = document.AddParagraphStyle("Quote")
    'Add a new paragraph to the section.
    Dim paragraph As IWParagraph = section.AddParagraph()
    'Apply Quote style to simple hello world text.
    paragraph.ApplyStyle("Quote")
    'Append text.
    Dim textRange As IWTextRange = paragraph.AppendText("Hello World")
    document.Save("WordToMd.md", FormatType.Markdown)
End Using

You can download a complete working sample from GitHub.

NOTE

Nested block quotes are not supported in a Word to the Markdown conversion. To preserve nested block quotes, add the number of “>” characters at the beginning of the paragraph in a Word document as equivalent to the nth nested level of the block quote. For example, to insert the 2nd nested level block quote, add two “>” characters at the start of the sentence, and no need to apply the “Quote” style to the paragraph.

Save Options

When converting a Word document to Markdown, the .NET Word (DocIO) library provides various save options to customize the output Markdown file. These options allow you to control image export location, customize image paths, set character encoding, and other export behaviors.

When converting a Word document to a Markdown using the Save(fileName) overloads, DocIO creates a new folder parallel to the output file name and exports all the images into it as default.

When converting a Word document to a Markdown using the Save(Stream, FormatType) overloads, DocIO preserves the images as base64 format in the output Markdown file as default.

Also, customize the above default behaviors using the following options in DocIO.

Export images to folder

Specify the folder location to export the images using the MarkdownExportImagesFolder API.

The following code example illustrates how set the images folder to export the images while converting a Word document to a Markdown file.

C# [Cross-platform]
C# [Windows-specific]
VB.NET [Windows-specific]
//Open an existing Word document.
using (WordDocument document = new WordDocument(Path.GetFullPath(@"Data/Input.docx")))
{
    //Set images folder to export images. 
    document.SaveOptions.MarkdownExportImagesFolder = "D:\\WordToMdConversion";
    //Save the document as a Markdown file.
    document.Save(Path.GetFullPath(@"Output/Output.md"));  
}
//Open an existing Word document. 
using (WordDocument document = new WordDocument("Input.docx", FormatType.Docx))
{
    //Set images folder to export images. 
    document.SaveOptions.MarkdownExportImagesFolder = "D:\\WordToMdConversion ";
    //Save a Word document as a Markdown file.
    document.Save("WordtoMd.md", FormatType.Markdown);
}
'Open an existing Word document.
Using document As WordDocument = New WordDocument("Input.docx")
    'Set images folder to export images. 
    document.SaveOptions.MarkdownExportImagesFolder = "D:\\WordToMdConversion ";
    'Save a document as a Markdown file.
    document.Save("WordtoMd.md")
End Using

You can download a complete working sample from GitHub.

Customize the image path

DocIO provides an ImageNodeVisited event, which is used to customize the image path to set in the output Markdown file and save images externally while converting a Word document to a Markdown.

The following code example illustrates how to save Image files during a Word to Markdown Conversion.

C# [Cross-platform]
C# [Windows-specific]
VB.NET [Windows-specific]
//Open an existing Word document.
 using (WordDocument document = new WordDocument(Path.GetFullPath(@"Data/Input.docx")))
 {
     //Hook the event to customize the image. 
     document.SaveOptions.MarkdownSaveOptions.ImageNodeVisited += SaveImage;
     //Save the document as a Markdown file.
     document.Save(Path.GetFullPath(@"Output/Output.md"));
 }
//Open an existing Word document. 
using (WordDocument document = new WordDocument(@"Input.docx"))
{
    //Hook the event to customize the image. 
    document.SaveOptions.MarkdownSaveOptions.ImageNodeVisited += SaveImage;
    //Save a Word document as a Markdown file.
    document.Save("WordtoMd.md", FormatType.Markdown);
}
'Open an existing Word document. 
Using document As WordDocument = New WordDocument("Input.docx")
    'Hook the event to customize the image. 
    document.SaveOptions.MarkdownSaveOptions.ImageNodeVisited += SaveImage
    'Save a Word document as a Markdown file.
    document.Save("WordtoMd.md", FormatType.Markdown)
End Using

The following code examples show the event handler to customize the image path and save the image in an external folder.

C# [Cross-platform]
C# [Windows-specific]
VB.NET [Windows-specific]
static void SaveImage(object sender, MdImageNodeVisitedEventArgs args)
{
    string imagepath = @"D:\Temp\Image1.png";
    //Save the image stream as a file.
    using (FileStream fileStreamOutput = File.Create(imagepath))
        args.ImageStream.CopyTo(fileStreamOutput);
    //Set the URI to be used for the image in the output Markdown. 
    args.Uri = imagepath;
}
static void SaveImage(object sender, MdImageNodeVisitedEventArgs args)
{
    string imagepath = @"D:\Temp\Image1.png";
    //Save the image stream as a file. 
    using (FileStream fileStreamOutput = File.Create(imagepath))
        args.ImageStream.CopyTo(fileStreamOutput);
    //Set the image URI to be used in the output markdown.
    args.Uri = imagepath;
}
Private Shared Sub SaveImage(ByVal sender As Object, ByVal args As MdImageNodeVisitedEventArgs)
    Dim imagepath = "D:\Temp\Image1.png"
    'Save the image stream as a file. 
    Using fileStreamOutput = File.Create(imagepath)
        args.ImageStream.CopyTo(fileStreamOutput)
    End Using
    'Set the URI to be used for the image in the output markdown. 
    args.Uri = imagepath
End Sub

You can download a complete working sample from GitHub.

NOTE

The MarkdownExportImagesFolderproperty and MarkdownSaveOptions.ImageNodeVisited event are not supported on the UWP platform.

Encoding

The .NET Word (DocIO) library provides an Encoding property to specify the character encoding to use when saving the Markdown file. This property is useful when you need to save the output Markdown file with specific character encodings such as UTF-8, UTF-16, ASCII, or other encodings.

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

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

NOTE

Set the encoding value before saving the document as per the above code example.

Supported Word document elements

The following table shows the list of Word document elements supported in Word to Markdown conversion.

Body items

Element in Word document	Notes
Paragraph	Preserved as one line.
Table	Preserves as per GitHub flavored Markdown syntax. Column alignment is based on alignment of first paragraph in cells of row. Nested tables are not supported in Markdown, and they are merged with contents of parent cell.
Block Content Control	Contents inside control controls are preserved as normal text. If the first item of the paragraph is a checkbox content control, then it preserves as a task item.

Paragraph items

Element in Word document	Notes
Field	Field result is preserved.
Form Field	Result of text and dropdown form fields are preserved.
Hyperlink	-
Image	-
Horizontal rule	-
Content Control	Contents inside control controls are preserved as normal text. If the first item of the paragraph is checkbox content control, then it preserves as a task item.
Breaks	Line and text wrapping breaks are supported.

Formatting

Element in Word document	Notes
Bold	-
Italic	-
StrikeThrough	-
Subscript and Superscript	-
Hidden	Considered as comments in Markdown syntax
List	Numbered and bulleted lists are supported. To restart numbering for the continuous list in the output markdown syntax, you should specify a non-empty paragraph in between the two lists in a Word document.

Online Demo

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

Search docs

Ask Syncfusion AI Assistant

Search docs

Ask Syncfusion AI Assistant

How can I help you?

Word to Markdown Conversion

Assemblies and NuGet packages required

Convert Word to Markdown

Design Word document for Markdown conversion

Code blocks

Block quotes

Save Options

Export images to folder

Customize the image path

Encoding

Supported Word document elements

Body items

Paragraph items

Formatting

Online Demo