Working with Markdown Features

This topic discusses how to implement Markdown features using Aspose.Words. Markdown is a simple way to format plain text that can easily be converted to HTML. Aspose.Words supports the following Markdown features:

• Headings
• Blockquotes
• Horizontal rules
• Bold emphasis
• Italic emphasis

The Markdown feature implementation mostly follows the CommonMark specification in Aspose.Words API and all the features are represented as corresponding styles or direct formatting. Which means that

• Bold and Italic are represented as Font.Bold and Font.Italic. 
• Headings are paragraphs with Heading 1 - Heading 6 styles. 
• Quotes are paragraphs with “Quote” in the style name. 
• HorizontalRule is a paragraph with HorizontalRule shape.

There are nuances of translating Markdown to the Aspose.Words Document Object Model (DOM), described in the article Translate Markdown to Document Object Model (DOM).

Markdown Document with Emphases

This section demonstrates you how to produce a markdown document with emphases as given below:

Markdown treats asterisks (*) and underscores (_) as indicators of emphasis.
You can write **bold** or *italic* text. 
You can also write ***BoldItalic*** text.

The following code snippet can be used to produce the above given markdown document.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

builder.Writeln("Markdown treats asterisks (*) and underscores (_) as indicators of emphasis.");
builder.Write("You can write ");

builder.Font.Bold = true;
builder.Write("bold");

builder.Font.Bold = false;
builder.Write(" or ");

builder.Font.Italic = true;
builder.Write("italic");

builder.Font.Italic = false;
builder.Writeln(" text. ");

builder.Write("You can also write ");
builder.Font.Bold = true;

builder.Font.Italic = true;
builder.Write("BoldItalic");

builder.Font.Bold = false;
builder.Font.Italic = false;
builder.Write("text.");

builder.Document.Save(ArtifactsDir + "WorkingWithMarkdown.Emphases.md");

Markdown Document with Headings

This section demonstrates you how to produce a markdown document with headings as given below:

The following produces headings:
# Heading1
## Heading2
### Heading3
#### Heading4
##### Heading5
###### Heading6
# **Bold Heading1**

The following code snippet can be used to produce the above given markdown document.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
// Use a document builder to add content to the document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// By default Heading styles in Word may have Bold and Italic formatting.
//If we do not want to be emphasized, set these properties explicitly to false.
builder.Font.Bold = false;
builder.Font.Italic = false;

builder.Writeln("The following produces headings:");
builder.ParagraphFormat.Style = doc.Styles["Heading 1"];
builder.Writeln("Heading1");
builder.ParagraphFormat.Style = doc.Styles["Heading 2"];
builder.Writeln("Heading2");
builder.ParagraphFormat.Style = doc.Styles["Heading 3"];
builder.Writeln("Heading3");
builder.ParagraphFormat.Style = doc.Styles["Heading 4"];
builder.Writeln("Heading4");
builder.ParagraphFormat.Style = doc.Styles["Heading 5"];
builder.Writeln("Heading5");
builder.ParagraphFormat.Style = doc.Styles["Heading 6"];
builder.Writeln("Heading6");

// Note, emphases are also allowed inside Headings:
builder.Font.Bold = true;
builder.ParagraphFormat.Style = doc.Styles["Heading 1"];
builder.Writeln("Bold Heading1");

doc.Save(ArtifactsDir + "WorkingWithMarkdown.Heading.md");

Markdown Document with Block Quotes

This section demonstrates you how to produce a markdown document with block quotes as given below:

> *Blockquote*
>> *1. Nested blockquote*
>>
>

The following code snippet can be used to produce the above given markdown document.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
// Use a document builder to add content to the document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// By default a document stores blockquote style for the first level.
builder.ParagraphFormat.StyleName = "Quote";
builder.Writeln("Blockquote");

// Create styles for nested levels through style inheritance.
Style quoteLevel2 = builder.Document.Styles.Add(StyleType.Paragraph, "Quote1");
builder.ParagraphFormat.Style = quoteLevel2;
builder.Document.Styles["Quote1"].BaseStyleName = "Quote";
builder.Writeln("1. Nested blockquote");

doc.Save(ArtifactsDir + "WorkingWithMarkdown.Quote.md");

Markdown Document with Horizontal Rule

This section demonstrates you how to produce a markdown document with Horizontal Rule as given below:

Insert a horizontal rule shape into the document.
-----

The following code snippet can be used to produce the above given markdown document.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

builder.Writeln("Insert a horizontal rule shape into the document.");
builder.InsertHorizontalRule();

doc.Save(ArtifactsDir + "AddContentUsingDocumentBuilder.InsertHorizontalRule.docx");

Reading a Markdown Document

The following code snippet shows you how to read a markdown document.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
Document doc = new Document(MyDir + "Quotes.md");

// Let's remove Heading formatting from a Quote in the very last paragraph.
Paragraph paragraph = doc.FirstSection.Body.LastParagraph;
paragraph.ParagraphFormat.Style = doc.Styles["Quote"];

doc.Save(ArtifactsDir + "WorkingWithMarkdown.ReadMarkdownDocument.md");

Specify Markdown Save Options

Aspose.Words API provides MarkdownSaveOptions class to specify additional options while saving a document into the Markdown format.

The following code example demonstrated how to specify various Markdown save options.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
Document doc = new Document(MyDir + "Image bullet points.docx");

MarkdownSaveOptions saveOptions = new MarkdownSaveOptions { ImagesFolder = ArtifactsDir + "Images" };

using (MemoryStream stream = new MemoryStream())
    doc.Save(stream, saveOptions);

How to Align Content Inside the Table while Exporting into Markdown

Aspose.Words API provides TableContentAlignment enumeration which defines alignment directions to align contents in tables while exporting into the Markdown document. The following code example demonstrates how to align content inside the table.

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET.git.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

builder.InsertCell();
builder.ParagraphFormat.Alignment = ParagraphAlignment.Right;
builder.Write("Cell1");
builder.InsertCell();
builder.ParagraphFormat.Alignment = ParagraphAlignment.Center;
builder.Write("Cell2");

// Makes all paragraphs inside the table to be aligned.
MarkdownSaveOptions saveOptions = new MarkdownSaveOptions
{
    TableContentAlignment = TableContentAlignment.Left
};
doc.Save(ArtifactsDir + "WorkingWithMarkdownSaveOptions.LeftTableContentAlignment.md", saveOptions);

saveOptions.TableContentAlignment = TableContentAlignment.Right;
doc.Save(ArtifactsDir + "WorkingWithMarkdownSaveOptions.RightTableContentAlignment.md", saveOptions);

saveOptions.TableContentAlignment = TableContentAlignment.Center;
doc.Save(ArtifactsDir + "WorkingWithMarkdownSaveOptions.CenterTableContentAlignment.md", saveOptions);

// The alignment in this case will be taken from the first paragraph in corresponding table column.
saveOptions.TableContentAlignment = TableContentAlignment.Auto;
doc.Save(ArtifactsDir + "WorkingWithMarkdownSaveOptions.AutoTableContentAlignment.md", saveOptions);