Convert a Document to Markdown

Markdown is a popular format used to markup text and its further converting to HTML, PDF, DOCX, or other formats. Many developers choose this format for writing documentation, preparing articles for publication on blogs, describing projects, and so on.

Markdown is so popular because it is easy to work with this format, as well as it can be quite simply converted to other formats. For this reason, Aspose.Words provides the ability to convert a document in any supported load format to Markdown and vice versa – Aspose.Words also supports the most popular save formats.

Now the functionality for working with the Markdown format is being actively developed to provide you with more opportunities for convenient and comfortable work with documents.

Convert a Document

To convert a document to Markdown, you just need to load a document in any supported format or create a new one programmatically. Then you need to save the document to Markdown format.

The following code example shows how to convert DOCX to Markdown:

For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
// Load the document from disk.
auto doc = System::MakeObject<Document>(inputDataDir + u"Test.docx");

// Save the document to Markdown format.
doc->Save(outputDataDir + u"SpecifyMarkdownSaveOptions.SaveAsMD.md");

You can also specify the physical folder in which you want to save images when exporting a document to Markdown format. By default, Aspose.Words saves images in the same folder where the document file is saved, but you can override this behavior using the ImagesFolder property.

Specifying a folder via ImagesFolder is also useful if you save a document to a stream and Aspose.Words does not have a folder for saving images.

If the specified ImagesFolder does not exist, it will be created automatically.

The following code example shows how to specify a folder for images when saving a document to a stream:

For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
// Load the document from disk.
auto doc = System::MakeObject<Document>(inputDataDir + u"Test.docx");

auto so = System::MakeObject<MarkdownSaveOptions>();
so->set_ImagesFolder(outputDataDir + u"\\Images");

auto stream = System::MakeObject<System::IO::MemoryStream>();
doc->Save(stream, so);

Specify Save Options when Converting to Markdown

Aspose.Words provides the ability to use the MarkdownSaveOptions class to work with advanced options when saving a document to Markdown format. Most properties are inheriting or overloading properties that already exist within other Aspose.Words.Saving Namespace classes. In addition to them, a number of properties that are specific for Markdown format have also been added. For example, the TableContentAlignment property to control the alignment of content in tables, or ImageSavingCallback and ImagesFolder to control how images are saved upon converting a document to Markdown format.

Supported Markdown Features

Aspose.Words currently supports the following Markdown features, which mostly follow the CommonMark specification in the Aspose.Words API and are represented as appropriate styles or direct formatting:

• Headings are paragraphs with Heading 1 – Heading 6 styles
• Blockquotes are paragraphs with “Quote” in the style name
• IndentedCode are paragraphs with “IndentedCode” in the style name
• FencedCode are paragraphs with “FencedCode” in the style name
• InlineCode are runs with “InlineCode” in the Font style name
• Horizontal rules are paragraphs with the HorizontalRule shape
• Bold emphasis
• Italic emphasis
• StrikeThrough formatting
• Lists are numbered or bulleted paragraphs
• Tables are represented with the Table class
• Links are represented as the FieldHyperlink class

The following example shows how to create a document with some styles and save it to Markdown:

For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
auto doc = System::MakeObject<Document>();
auto builder = System::MakeObject<DocumentBuilder>(doc);


// Specify the "Heading 1" style for the paragraph.
builder->InsertParagraph();
builder->get_ParagraphFormat()->set_StyleName(u"Heading 1");
builder->Write(u"Heading 1");

// Specify the Italic emphasis for the paragraph.
builder->InsertParagraph();
// Reset styles from the previous paragraph to not combine styles between paragraphs.
builder->get_ParagraphFormat()->set_StyleName(u"Normal");
builder->get_Font()->set_Italic(true);
builder->Write(u"Italic Text");
// Reset styles from the previous paragraph to not combine styles between paragraphs.
builder->set_Italic(false);

// Specify a Hyperlink for the desired text.
builder->InsertParagraph();
builder->InsertHyperlink(u"Aspose", u"https://www.aspose.com", false);
builder->Write(u"Aspose");

// Save your document as a Markdown file.
doc->Save(outputDataDir + u"SpecifyMarkdownSaveOptions.SupportedMarkdownFeatures.md");

The result of this code example is shown below.

Useful Tips

There are several nuances and interesting cases, having learned which you can work with Markdown files more flexibly and conveniently. For example, there is the ability to use:

• SetextHeading that allows you to create multi-line headings in Markdown, while regular headings in Markdown can only be single-line. SetextHeading is based on a “Heading N” style, and its level can only be 1 or 2. If N in “Heading N” is greater than or equal to 2, then the corresponding SetextHeading is based on “Heading 2”, otherwise on “Heading 1”.
• Different markers for the first level of bulleted lists ("-", “+” or “*”, the default marker is “-”.) and different types of numbering for ordered lists ("." or “)”, the default marker is “.").