Parse and Process Markdown in C#

Parse Markdown to a Syntax Tree (Markdown AST) in C#

Aspose.HTML for .NET provides a dedicated Markdown parsing API in the Aspose.Html.Toolkit.Markdown.Syntax namespace. The MarkdownParse class converts a .md file into a strongly typed MarkdownSyntaxTree – a Markdown Abstract Syntax Tree (AST) that represents the full document structure.

Each Markdown element is mapped to a specific node type:

• AtxHeadingSyntaxNode – ATX headings (#, ##, etc.)
• TableSyntaxNode – GFM tables
• InlineLinkSyntaxNode – inline links
• FencedCodeBlockSyntaxNode – fenced code blocks
• and other syntax node classes

Unlike text-based Markdown converters, this API gives you direct programmatic access to the document structure before rendering. Instead of converting Markdown to HTML first, you can analyze, validate, filter, or modify the syntax tree at the structural level.

To build a syntax tree:

using Aspose.Html.Toolkit.Markdown.Syntax.Parser;

var parser = new MarkdownParser();
var syntaxTree = parser.ParseFile("document.md");

syntaxTree is the root node of the Markdown AST and provides access to all child nodes in the document. In the following sections, you will learn how to traverse the syntax tree, extract headings and tables, and filter nodes by type.

Traverse the Markdown Syntax Tree in C#

Once the Markdown file is parsed into a MarkdownSyntaxTree, you can traverse its nodes to inspect or process document elements. The Markdown API does not support index-based access to children. The NodeList returned by ChildNodes() has no indexer. Instead, traversal follows a pointer-based pattern using:

• FirstChild
• NextSibling

Example: iterating through top-level nodes of the document:

var node = syntaxTree.FirstChild;

while (node != null)
{
    // Process node
    Console.WriteLine(node.GetType().Name);

    node = node.NextSibling;
}

This pattern ensures efficient and safe traversal of the Markdown AST without relying on list indexing.

For more advanced scenarios, such as visiting only specific node types (e.g., tables or headings), you can use CreateTreeWalker() together with a MarkdownSyntaxNodeFilter. This approach enables selective traversal of the syntax tree.

Extract Headings from a Markdown in C#

After parsing a Markdown file into a MarkdownSyntaxTree, you can programmatically extract specific node types. This example demonstrates how to locate all ATX-style headings (#, ##, ###), determine their nesting level (H1–H6), and reconstruct their hierarchy using the Markdown AST.

using System.Text;
using Aspose.Html.Toolkit.Markdown.Syntax;
using Aspose.Html.Toolkit.Markdown.Syntax.Parser;
using System.IO;
...

// Parse a Markdown file and extract ATX headings (# H1, ## H2, ### H3)
// preserving their hierarchy and nesting level using Aspose.HTML for .NET.

// Initialize the parser and build a syntax tree from the .md file
var parser = new MarkdownParser();
var syntaxTree = parser.ParseFile("document.md");

var headings = new List<(int Level, string Text)>();

// Walk top-level nodes using FirstChild -> NextSibling
var topNode = syntaxTree.FirstChild;
while (topNode != null)
{
    if (topNode is AtxHeadingSyntaxNode heading)
    {
        // Determine heading level (1–6)ns
        int level = heading.GetLeadingTrivia()
                           .Count(t => t.ToString().Trim() == "#");

        if (level == 0)
            level = heading.ToString().TakeWhile(c => c == '#').Count();

        // Extract heading text from child nodes
        var sb = new StringBuilder();
        var child = heading.FirstChild;
        while (child != null)
        {
            if (child is TextSyntaxNode || child is WhitespaceSyntaxNode)
                sb.Append(child.ToString());
            child = child.NextSibling;
        }

        headings.Add((level, sb.ToString().Trim()));
    }

    topNode = topNode.NextSibling;
}

// Output heading hierarchy with indentation reflecting nesting depth
foreach (var (level, text) in headings)
{
    string indent = new string(' ', (level - 1) * 2);
    string marker = new string('#', level);
    Console.WriteLine($"{indent}{marker} {text}");
}

How ATX Heading Extraction Works

1. MarkdownParser.ParseFile() builds a MarkdownSyntaxTree, which represents the full Markdown Abstract Syntax Tree (AST).
2. Traversal begins at syntaxTree.FirstChild and continues through NextSibling. The Markdown API does not support indexed access to NodeList, so pointer-based traversal is required.
3. AtxHeadingSyntaxNode identifies headings defined with leading # characters. (Setext-style headings are represented by SetextHeadingSyntaxNode and are not handled in this example.)
4. The heading level is determined by counting leading # tokens via GetLeadingTrivia(). A fallback counts # characters directly from the node string.
5. The heading text is reconstructed from TextSyntaxNode and WhitespaceSyntaxNode children. Structural nodes such as SoftBreakSyntaxNode are intentionally ignored.

Extract GFM Tables from the Markdown in C#

After parsing Markdown into a MarkdownSyntaxTree, you can selectively traverse the Markdown AST to locate specific node types. This example demonstrates how to extract GitHub Flavored Markdown (GFM) tables using a TreeWalker together with a custom MarkdownSyntaxNodeFilter.

Unlike manual top-level traversal, this approach walks the entire syntax tree and returns only nodes that match the specified type.

using System.Text;
using Aspose.Html.Toolkit.Markdown.Syntax;
using Aspose.Html.Toolkit.Markdown.Syntax.Parser;
using System.IO;
...

// Parse Markdown and extract GFM tables using TreeWalker

// Initialize the parser and build a syntax tree from the .md file
var parser = new MarkdownParser();
var syntaxTree = parser.ParseFile("document.md");

// Create a TreeWalker that visits only TableSyntaxNode nodes
using var tableWalker = syntaxTree.CreateTreeWalker(new TypeFilter<TableSyntaxNode>());

MarkdownSyntaxNode current;
while ((current = tableWalker.NextNode()) != null)
{
    if (current is not TableSyntaxNode table) continue;

    // Iterate rows via FirstChild -> NextSibling
    var row = table.FirstChild;
    while (row != null)
    {
        if (row is TableRowSyntaxNode tableRow)
        {
            var sb = new StringBuilder();
            var cell = tableRow.FirstChild;
            while (cell != null)
            {
                if (cell is TableCellSyntaxNode)
                    sb.Append($"| {cell.ToString().Trim()} ");
                cell = cell.NextSibling;
            }
            if (sb.Length > 0)
                Console.WriteLine(sb.Append('|').ToString());
        }
        row = row.NextSibling;
    }
}

// Custom filter that accepts only nodes of type T
class TypeFilter<T> : MarkdownSyntaxNodeFilter where T : MarkdownSyntaxNode
{
    public override short AcceptNode(MarkdownSyntaxNode node)
        => node is T ? (short)1 : (short)3;
}

How Markdown Table Extraction with TreeWalker Works

1. MarkdownParser.ParseFile() builds a MarkdownSyntaxTree, representing the full Markdown AST.
2. CreateTreeWalker(MarkdownSyntaxNodeFilter) creates a filtered traversal mechanism that walks the entire tree but returns only nodes accepted by the filter.
3. The custom TypeFilter<TableSyntaxNode> inherits from MarkdownSyntaxNodeFilter and overrides AcceptNode().
   • 1 (FILTER_ACCEPT) includes the node
   • 3 (FILTER_SKIP) ignores it
4. NextNode() advances through the Markdown AST and yields only TableSyntaxNode instances.
5. Rows (TableRowSyntaxNode) and cells (TableCellSyntaxNode) are accessed using pointer-based traversal (FirstChild → NextSibling), since NodeList does not support index access.
6. cell.ToString().Trim() extracts the textual content of each table cell.

Modify Markdown Syntax Tree in C#

MarkdownSyntaxTree is mutable. You can traverse nodes, modify their content, replace children, and save the updated Markdown document.

The following code modifies Markdown emphasis nodes in a syntax tree using Aspose.HTML for .NET. It replaces all occurrences of a deprecated product name (Aspose.HTML) with a new one (Aspose.HTML for .NET) – directly via the syntax tree, without using regex or string replacement.

using Aspose.Html.Toolkit.Markdown.Syntax;
using Aspose.Html.Toolkit.Markdown.Syntax.Parser;
using System.IO;
...

string markdownContent =
    "# Release Notes\n\n" +
    "* Aspose.HTML * is a powerful HTML processing library.\n" +
    "Use *Aspose.HTML* to convert, parse, and manipulate HTML documents.\n" +
    "The latest version of *Aspose.HTML* includes Markdown support.";

// Parse markdown
var markdown = new MarkdownParser().Parse(markdownContent);
var factory = markdown.SyntaxFactory;

// Recursively traverse and replace text in Emphasis nodes
void ReplaceInEmphasis(MarkdownSyntaxNode node, string oldText, string newText)
{
    // Check if current node is Emphasis with target text
    if (node is EmphasisSyntaxNode em && 
        em.ToString().Trim('*').Trim() == oldText)
    {
        // Clear existing content
        while (em.FirstChild != null) 
            em.RemoveChild(em.FirstChild);
        // Insert new text
        em.AppendChild(factory.Text(newText));
    }
    // Recurse into children
    for (var c = node.FirstChild; c != null; c = c.NextSibling)
        ReplaceInEmphasis(c, oldText, newText);
}

// Run replacement on entire document
ReplaceInEmphasis(markdown, "Aspose.HTML", "Aspose.HTML for .NET");

// Save result to file
markdown.Save(Path.Combine(OutputDir, "modified-release-notes.md"));

Quick Reference: Markdown Parsing in C#

How to parse a Markdown file into a syntax tree?

var syntaxTree = new MarkdownParser().ParseFile("document.md");

Builds a MarkdownSyntaxTree – the root of the Markdown AST that represents the full document structure.

How to iterate top-level nodes in the Markdown AST?

var node = syntaxTree.FirstChild;
while (node != null)
{
    /* process node */
    node = node.NextSibling;
}

NodeList returned by ChildNodes() does not support index access. Use pointer-based traversal: FirstChild → NextSibling.

How to check whether a node is a heading?

if (node is AtxHeadingSyntaxNode heading)
{
    /* H1–H6 heading */
}

AtxHeadingSyntaxNode represents ATX-style headings (#, ##, … ######) in the Markdown syntax tree.

How to traverse only specific node types using a filter?

using var walker = syntaxTree.CreateTreeWalker(new TypeFilter<TableSyntaxNode>());

while (walker.NextNode() != null)
{
    /* only TableSyntaxNode nodes */
}

TypeFilter<T> is a custom MarkdownSyntaxNodeFilter that accepts only nodes of type T, enabling selective traversal of the Markdown AST.

FAQ: Markdown Parsing with Aspose.HTML

Q: What is the difference between AtxHeadingSyntaxNode and SetextHeadingSyntaxNode?

AtxHeadingSyntaxNode represents headings defined with leading # characters (# H1, ## H2). SetextHeadingSyntaxNode represents headings underlined with = or - on the next line. Both are valid Markdown heading styles, but they map to different node classes in the syntax tree.

Q: Why does NodeList not support index access like children[0]?

NodeList in the Aspose.HTML Markdown API does not implement IList<T> and has no indexer. The correct traversal pattern is pointer-based: start from FirstChild and advance through siblings using NextSibling until the value is null.

Q: Does TreeWalker traverse the entire document or only direct children?

CreateTreeWalker(syntaxTree.FirstChild) starts traversal from the first child node and visits only its descendants. To traverse the entire document, pass a MarkdownSyntaxNodeFilter directly: CreateTreeWalker(filter) – this starts from the tree root and visits all nodes.

In this guide, you learned how to:

• Parse Markdown
• Traverse the AST
• Extract structured elements
• Modify content programmatically

Related Articles

• Markdown Syntax – Basic Tutorial – Overview of Markdown elements and syntax rules.
• Markdown Converter – C# – Convert Markdown to HTML and other formats using Aspose.HTML for .NET.
• Create Markdown Documents in C# – Create Markdown documents programmatically using Aspose.HTML for .NET: build headings, paragraphs, lists, and save Markdown files from scratch.
• Edit Markdown Files in C# – Edit Markdown files in C# with Aspose.HTML for .NET: change headings, update paragraphs, remove list items. Working code examples + AST manipulation guide.