Site/Docs/Advanced/Ast Copy Section

---
title: Abstract syntax tree
---

Abstract syntax tree

The Markdown.Parse(...) method returns a MarkdownDocument — the root of the abstract syntax tree (AST). The AST is a tree of Block and Inline nodes that fully represents the semantic structure of the Markdown input.

AST structure Copy Chapter

There are two general categories of node:

- Block nodes — Represent block-level constructs: paragraphs, headings, lists, code blocks, blockquotes, etc.
- Inline nodes — Represent inline constructs within a block: emphasis, links, code spans, images, line breaks, etc.

Blocks may contain other blocks (container blocks) or inlines (leaf blocks). Inlines may contain other inlines (container inlines) but never blocks.

MarkdownDocument (ContainerBlock)
├── HeadingBlock (LeafBlock)
│   └── LiteralInline
├── ParagraphBlock (LeafBlock)
│   ├── LiteralInline
│   ├── EmphasisInline (ContainerInline)
│   │   └── LiteralInline
│   └── LiteralInline
├── ListBlock (ContainerBlock)
│   ├── ListItemBlock (ContainerBlock)
│   │   └── ParagraphBlock
│   └── ListItemBlock (ContainerBlock)
│       └── ParagraphBlock
└── FencedCodeBlock (LeafBlock)

Node hierarchy Copy Chapter

All AST nodes inherit from MarkdownObject, which provides:

{.table}
| Member | Type | Description |
|---|---|---|
| Span | SourceSpan | Start and end positions (inclusive) in the source text |
| Line | int | Zero-based line number in the source |
| Column | int | Zero-based column number |

Block types Copy Section

{.table}
| Base class | Description | Examples |
|---|---|---|
| ContainerBlock | Contains child blocks | MarkdownDocument, ListBlock, ListItemBlock, QuoteBlock |
| LeafBlock | Contains inlines, no child blocks | ParagraphBlock, HeadingBlock, CodeBlock, FencedCodeBlock |

A LeafBlock has an Inline property (ContainerInline?) that is the root of its inline content.

Inline types Copy Section

{.table}
| Base class | Description | Examples |
|---|---|---|
| ContainerInline | Contains child inlines | EmphasisInline, LinkInline |
| LeafInline | No children | LiteralInline, CodeInline, LineBreakInline |

Inlines are stored as a doubly-linked list — each inline has PreviousSibling and NextSibling properties, plus a Parent (ContainerInline?).

Traversing the AST Copy Chapter

The Descendants API Copy Section

The Descendants extension methods provide the easiest way to traverse the tree. They yield nodes in depth-first order.

#### All descendants

var document = Markdown.Parse(markdownText);
foreach (var node in document.Descendants())
{
    Console.WriteLine($"{node.GetType().Name} at {node.Line}:{node.Column}");
}

#### Filter by type

// All headings
foreach (var heading in document.Descendants<HeadingBlock>())
{
    Console.WriteLine($"H{heading.Level}: line {heading.Line}");
}
// All links (not images)
foreach (var link in document.Descendants<LinkInline>().Where(l => !l.IsImage))
{
    Console.WriteLine($"Link: {link.Url}");
}
// All images
foreach (var image in document.Descendants<LinkInline>().Where(l => l.IsImage))
{
    Console.WriteLine($"Image: {image.Url}");
}

#### Querying from any node

Descendants works from any MarkdownObject, not just the root:

// Find all emphasis inside list items
var items = document.Descendants<ListItemBlock>()
    .SelectMany(item => item.Descendants<EmphasisInline>());
// Find emphasis whose direct parent block is a list item
var other = document.Descendants<EmphasisInline>()
    .Where(em => em.ParentBlock is ListItemBlock);

Manual traversal Copy Section

For containers you can iterate children directly:

// Block children of a ContainerBlock
foreach (var child in document)
{
    // child is a Block
}
// Inline children of a ContainerInline
var paragraph = document.Descendants<ParagraphBlock>().First();
var inline = paragraph.Inline; // ContainerInline?
if (inline != null)
{
    var child = inline.FirstChild;
    while (child != null)
    {
        Console.WriteLine(child.GetType().Name);
        child = child.NextSibling;
    }
}

Common block types Copy Chapter

{.table}
| Type | Description |
|---|---|
| MarkdownDocument | Root node, a ContainerBlock |
| ParagraphBlock | A paragraph (<p>) |
| HeadingBlock | A heading (<h1>–<h6>); has Level property |
| ListBlock | An ordered or unordered list |
| ListItemBlock | A single list item |
| QuoteBlock | A blockquote |
| FencedCodeBlock | A fenced code block; has Info (language) and Lines properties |
| CodeBlock | An indented code block |
| ThematicBreakBlock | A horizontal rule (<hr>) |
| HtmlBlock | A raw HTML block |

Common inline types Copy Chapter

{.table}
| Type | Description |
|---|---|
| LiteralInline | Plain text content |
| EmphasisInline | Emphasis (<em> or <strong>); has DelimiterChar and DelimiterCount |
| CodeInline | Inline code span |
| LinkInline | A link or image; has Url, Title, IsImage |
| AutolinkInline | An autolink (<url>) |
| LineBreakInline | A line break (hard or soft) |
| HtmlInline | Inline raw HTML |
| HtmlEntityInline | An HTML entity |

Attached data Copy Chapter

Every MarkdownObject supports attaching arbitrary key-value data:

// Store data
node.SetData("my-key", someValue);
// Retrieve data
var value = node.GetData("my-key");
// Check existence
if (node.ContainsData("my-key")) { ... }
// Remove
node.RemoveData("my-key");

Typed metadata helpers Copy Section

For extension state, prefer collision-resistant typed keys via DataKey<T> and the typed helper methods:

using Markdig.Syntax;
public sealed class MyExtensionState
{
    public int Value { get; set; }
}
static readonly DataKey<MyExtensionState> StateKey = new();
// Store
node.SetData<MyExtensionState>(StateKey, new MyExtensionState { Value = 123 });
// Retrieve
if (node.TryGetData<MyExtensionState>(StateKey, out var state))
{
    Console.WriteLine(state.Value);
}

HTML attributes Copy Section

The most common attached data is HtmlAttributes, used by the Generic attributes extension:

using Markdig.Renderers.Html;
var attrs = node.GetAttributes(); // Creates if not present
attrs.AddClass("my-class");
attrs.Id = "my-id";
attrs.AddProperty("data-value", "42");

Mutating the AST safely Copy Chapter

Markdig provides a few small helpers for common AST "surgery" operations:

// Remove a block from its parent container
block.Remove();
// Replace a block in its parent container (optionally transferring children)
block.ReplaceBy(replacementBlock, moveChildren: true);
// Transfer children efficiently (preserves order)
sourceContainerBlock.TransferChildrenTo(destinationContainerBlock);
sourceContainerInline.TransferChildrenTo(destinationContainerInline);

These helpers preserve parent/child ownership invariants and avoid common O(n²) patterns (for example repeatedly calling RemoveAt(0) on a ContainerBlock).

The SourceSpan struct Copy Chapter

Every node has a Span property of type SourceSpan with Start and End positions (inclusive) in the original source. When .UsePreciseSourceLocation() is enabled, these values are accurate for all nodes.

var pipeline = new MarkdownPipelineBuilder()
    .UsePreciseSourceLocation()
    .Build();
var document = Markdown.Parse(markdownText, pipeline);
foreach (var heading in document.Descendants<HeadingBlock>())
{
    var span = heading.Span;
    var sourceText = markdownText[span.Start..(span.End + 1)];
    Console.WriteLine($"Heading source: '{sourceText}'");
}

Block properties Copy Chapter

IsOpen Copy Section

While a block is being parsed, IsOpen is true. Once the parser finishes building the block, IsOpen is set to false. In a fully parsed document, all blocks have IsOpen == false.

IsBreakable Copy Section

Indicates whether the block can be interrupted by new blocks. FencedCodeBlock is the only built-in non-breakable block — its parent container cannot be closed while the code block is still open, because content inside the fence is treated as literal code.

Parent Copy Section

Every block has a Parent (ContainerBlock?) property for upward traversal. The root MarkdownDocument has Parent == null.

Parser Copy Section

Every block stores a reference to the BlockParser that created it. This is useful when post-processing needs to identify which parser produced a given node.

---

Site/Docs/Advanced/Block Parsers Copy Section

---
title: Block parsers
---

Block parsers

Block parsers identify block-level elements (paragraphs, headings, lists, code blocks, custom containers, etc.) from the Markdown source text. They run during the first phase of parsing, processing the document line by line.

How block parsing works Copy Chapter

The BlockProcessor orchestrates block parsing. For each line in the source:

1. Continue — All currently open blocks are asked if they continue on the current line (TryContinue). Blocks that don't continue are closed.
2. Open — The processor tries to open new blocks by calling TryOpen on block parsers whose OpeningCharacters match the current character.
3. Dispatch — Parsers are dispatched based on their OpeningCharacters array — a parser is only tried when one of its opening characters matches the current position.

The BlockParser base class Copy Chapter

All block parsers inherit from BlockParser:

public abstract class BlockParser : ParserBase<BlockProcessor>, IBlockParser<BlockProcessor>
{
    // Characters that trigger this parser
    public char[]? OpeningCharacters { get; set; }
    // Whether this parser can interrupt an open paragraph
    public virtual bool CanInterrupt(BlockProcessor processor, Block block) => true;
    // Try to open a new block at the current position
    public abstract BlockState TryOpen(BlockProcessor processor);
    // Try to continue an already-open block
    public virtual BlockState TryContinue(BlockProcessor processor, Block block)
        => BlockState.None;
    // Called when a block is closing. Return false to remove it from the AST.
    public virtual bool Close(BlockProcessor processor, Block block) => true;
    // Event fired when a block is closed
    public event ProcessBlockDelegate? Closed;
}

BlockState return values Copy Chapter

The TryOpen and TryContinue methods return a BlockState enum:

{.table}
| Value | Meaning |
|---|---|
| None | No match — parser did not recognize anything |
| Skip | Skip this parser for the current line, try others |
| Continue | Block stays open; for leaf blocks, the line content is appended |
| ContinueDiscard | Block stays open; line is consumed but not appended to the block |
| Break | Block is closed; current line remains available for other parsers |
| BreakDiscard | Block is closed; current line is consumed (not available to others) |

Writing a custom block parser Copy Chapter

Step 1: Define the AST node Copy Section

Create a class inheriting from LeafBlock (for blocks with inline content) or ContainerBlock (for blocks containing other blocks):

using Markdig.Parsers;
using Markdig.Syntax;
/// <summary>
/// A custom note block: !!! note "Title"
/// </summary>
public class NoteBlock : LeafBlock
{
    public NoteBlock(BlockParser parser) : base(parser)
    {
    }
    /// <summary>
    /// The note title.
    /// </summary>
    public string? Title { get; set; }
    /// <summary>
    /// The note type (note, warning, etc.).
    /// </summary>
    public string? NoteType { get; set; }
}

Step 2: Implement the block parser Copy Section

/ Detailed source-code truncated for AI context efficiency. /

Step 3: Key points about TryOpen Copy Section

- Check processor.IsCodeIndent — If the line is indented 4+ spaces, it's a code block, not your custom syntax.
- Set the Parser property — The Block constructor automatically sets it from the argument.
- Set Span, Line, and Column — These enable precise source location tracking.
- Support trivia when enabled — If processor.TrackTrivia is true, take pending leading blank/trivia lines via processor.TakeLinesBefore() and assign them to block.LinesBefore (and use processor.UseTrivia(end) when you need exact trivia slices around markers).
- Push to processor.NewBlocks — This tells the processor a new block was found.
- Return the right BlockState — Break for a single-line block, Continue for multi-line blocks.

Multi-line block parsers Copy Chapter

For blocks that span multiple lines, use TryContinue:

public class AdmonitionParser : BlockParser
{
    public AdmonitionParser()
    {
        OpeningCharacters = ['!'];
    }
    public override BlockState TryOpen(BlockProcessor processor)
    {
        if (processor.IsCodeIndent) return BlockState.None;
        var line = processor.Line;
        if (line.CurrentChar != '!' || line.PeekChar(1) != '!' || line.PeekChar(2) != '!')
            return BlockState.None;
        line.Start += 3;
        line.TrimStart();
        var block = new AdmonitionBlock(this)
        {
            // ... set properties
        };
        processor.NewBlocks.Push(block);
        return BlockState.Continue; // Expect more lines
    }
    public override BlockState TryContinue(BlockProcessor processor, Block block)
    {
        // Continue while lines are indented (part of the admonition)
        if (processor.IsBlankLine)
            return BlockState.Continue; // Blank lines are allowed
        if (processor.Indent >= 4)
        {
            // Indented content belongs to this block
            processor.GoToColumn(processor.ColumnBeforeIndent + 4);
            return BlockState.Continue;
        }
        // Not indented — close the block
        return BlockState.Break;
    }
}

Using FencedBlockParserBase Copy Chapter

For blocks that use opening/closing fences (like ::: custom containers or `` code blocks), inherit from FencedBlockParserBase<T> to get fencing logic for free:

using Markdig.Parsers;
/// <summary>
/// A custom "spoiler" block: |||spoiler ... |||
/// </summary>
public class SpoilerBlock : FencedCodeBlock
{
    public SpoilerBlock(BlockParser parser) : base(parser) { }
}
public class SpoilerParser : FencedBlockParserBase<SpoilerBlock>
{
    public SpoilerParser()
    {
        OpeningCharacters = ['|'];
        InfoPrefix = null; // No info string prefix required
    }
    protected override SpoilerBlock CreateFencedBlock(BlockProcessor processor)
    {
        return new SpoilerBlock(this);
    }
}

public override bool CanInterrupt(BlockProcessor processor, Block block)
{
    // Only allow after a blank line, not in the middle of a paragraph
    return false;
}

Close is called when a block is being finalized. Return false to remove the block from the AST (useful if the block turned out to be invalid):

public override bool Close(BlockProcessor processor, Block block)
{
    var myBlock = (MyBlock)block;
    if (!myBlock.IsValid)
    {
        return false; // Remove from AST
    }
    return true; // Keep in AST
}

Trivia tracking Copy Chapter

When TrackTrivia is enabled, use processor.TakeLinesBefore() in TryOpen to capture pending blank/trivia lines:

public override BlockState TryOpen(BlockProcessor processor)
{
    // ... detection logic ...
    var block = new MyBlock(this);
    block.LinesBefore = processor.TakeLinesBefore();
    processor.NewBlocks.Push(block);
    return BlockState.Continue;
}

Next steps Copy Chapter

- Inline parsers — Write parsers for inline elements
- Renderers — Create HTML renderers for your custom blocks
- Creating extensions — Wire everything together

---

Site/Docs/Advanced/Creating Extensions Copy Section

---
title: Creating extensions
---

Creating extensions

Extensions are the primary mechanism for adding new features to Markdig. An extension can add new parsers, modify existing parsers, and register custom renderers.

The IMarkdownExtension interface Copy Chapter

Every extension implements IMarkdownExtension, which has two methods:

public interface IMarkdownExtension
{
    void Setup(MarkdownPipelineBuilder pipeline);
    void Setup(MarkdownPipeline pipeline, IMarkdownRenderer renderer);
}

- Setup(MarkdownPipelineBuilder) — Called when the pipeline is built. Register or modify block/inline parsers here.
- Setup(MarkdownPipeline, IMarkdownRenderer) — Called before rendering. Register object renderers here.

Extension complexity spectrum Copy Chapter

Extensions range from trivial to complex:

Level 1: Modify an existing parser Copy Section

The simplest extensions don't add new parsers at all — they just tweak existing ones.

Example: CitationExtension — Adds ""..."" citations by configuring the existing EmphasisInlineParser:

using Markdig;
using Markdig.Parsers.Inlines;
using Markdig.Renderers;
using Markdig.Renderers.Html.Inlines;
public sealed class CitationExtension : IMarkdownExtension
{
    public void Setup(MarkdownPipelineBuilder pipeline)
    {
        // Find the existing emphasis parser
        var emphasisParser = pipeline.InlineParsers.FindExact<EmphasisInlineParser>();
        if (emphasisParser != null && !emphasisParser.HasEmphasisChar('"'))
        {
            // Add " as a 2-character emphasis delimiter: ""text""
            emphasisParser.EmphasisDescriptors.Add(
                new EmphasisDescriptor('"', 2, 2, false));
        }
    }
    public void Setup(MarkdownPipeline pipeline, IMarkdownRenderer renderer)
    {
        if (renderer is not HtmlRenderer) return;
        // Hook into the emphasis renderer to emit <cite> for ""...""
        var emphasisRenderer = renderer.ObjectRenderers.FindExact<EmphasisInlineRenderer>();
        if (emphasisRenderer == null) return;
        var previousTag = emphasisRenderer.GetTag;
        emphasisRenderer.GetTag = inline =>
            (inline.DelimiterCount == 2 && inline.DelimiterChar == '"' ? "cite" : null)
            ?? previousTag(inline);
    }
}

Key pattern: Reuse EmphasisInlineParser for delimiter-based inlines. Many extensions follow this approach.

Level 2: Add a new inline parser + renderer Copy Section

When you need custom inline syntax that doesn't fit the emphasis model.

Example: TaskListExtension — Adds [ ] / [x] checkbox parsing:

public sealed class TaskListExtension : IMarkdownExtension
{
    public void Setup(MarkdownPipelineBuilder pipeline)
    {
        // Insert the task list parser before the link parser
        if (!pipeline.InlineParsers.Contains<TaskListInlineParser>())
        {
            pipeline.InlineParsers.InsertBefore<LinkInlineParser>(
                new TaskListInlineParser());
        }
    }
    public void Setup(MarkdownPipeline pipeline, IMarkdownRenderer renderer)
    {
        if (renderer is HtmlRenderer htmlRenderer)
        {
            htmlRenderer.ObjectRenderers.AddIfNotAlready<HtmlTaskListRenderer>();
        }
    }
}

This extension needs:
- A custom InlineParser subclass (TaskListInlineParser)
- A custom AST node (TaskList inline)
- A custom HtmlObjectRenderer<TaskList> (HtmlTaskListRenderer)

Level 3: Add a new block parser + renderer Copy Section

When you need to parse block-level constructs.

Example: CustomContainerExtension — Adds ::: fenced containers:

public sealed class CustomContainerExtension : IMarkdownExtension
{
    public void Setup(MarkdownPipelineBuilder pipeline)
    {
        // Add the block parser at position 0 (high priority)
        if (!pipeline.BlockParsers.Contains<CustomContainerParser>())
        {
            pipeline.BlockParsers.Insert(0, new CustomContainerParser());
        }
        // Also add inline container support (::text::)
        var emphasisParser = pipeline.InlineParsers.FindExact<EmphasisInlineParser>();
        if (emphasisParser != null && !emphasisParser.HasEmphasisChar(':'))
        {
            emphasisParser.EmphasisDescriptors.Add(
                new EmphasisDescriptor(':', 2, 2, false));
        }
    }
    public void Setup(MarkdownPipeline pipeline, IMarkdownRenderer renderer)
    {
        if (renderer is HtmlRenderer htmlRenderer)
        {
            htmlRenderer.ObjectRenderers.AddIfNotAlready<HtmlCustomContainerRenderer>();
            htmlRenderer.ObjectRenderers.AddIfNotAlready<HtmlCustomContainerInlineRenderer>();
        }
    }
}

Level 4: Complex extension with multiple parsers and ordering Copy Section

Some extensions (like FootnoteExtension) add multiple block parsers, inline parsers, and renderers, and need specific ordering relative to other extensions. These are more complex but follow the same fundamental patterns.

Registering your extension Copy Chapter

Option A: Generic Use method Copy Section

For extensions with a parameterless constructor:

var pipeline = new MarkdownPipelineBuilder()
    .Use<MyExtension>()
    .Build();

Option B: Instance method Copy Section

For extensions that need configuration:

var ext = new MyExtension(someConfig);
var pipeline = new MarkdownPipelineBuilder()
    .Use(ext)
    .Build();

Option C: Custom fluent extension method (recommended) Copy Section

Create an extension method on MarkdownPipelineBuilder for a clean API:

public static class MyExtensionMethods
{
    public static MarkdownPipelineBuilder UseMyExtension(
        this MarkdownPipelineBuilder pipeline,
        MyExtensionOptions? options = null)
    {
        pipeline.Extensions.ReplaceOrAdd<MyExtension>(
            new MyExtension(options));
        return pipeline;
    }
}

Usage:

var pipeline = new MarkdownPipelineBuilder()
    .UseMyExtension(new MyExtensionOptions { / ... / })
    .Build();

Complete example: a blink extension Copy Chapter

Here's a complete, silly extension that turns %%%text%%% into <blink>text</blink>:

using Markdig;
using Markdig.Parsers.Inlines;
using Markdig.Renderers;
using Markdig.Renderers.Html.Inlines;
/// <summary>
/// Extension that converts %%%text%%% to &lt;blink&gt; tags.
/// </summary>
public sealed class BlinkExtension : IMarkdownExtension
{
    public void Setup(MarkdownPipelineBuilder pipeline)
    {
        var parser = pipeline.InlineParsers.FindExact<EmphasisInlineParser>();
        if (parser != null && !parser.HasEmphasisChar('%'))
        {
            // 3 consecutive % on each side
            parser.EmphasisDescriptors.Add(new EmphasisDescriptor('%', 3, 3, false));
        }
    }
    public void Setup(MarkdownPipeline pipeline, IMarkdownRenderer renderer)
    {
        if (renderer is not HtmlRenderer) return;
        var emphasisRenderer = renderer.ObjectRenderers.FindExact<EmphasisInlineRenderer>();
        if (emphasisRenderer == null) return;
        var previousTag = emphasisRenderer.GetTag;
        emphasisRenderer.GetTag = inline =>
            (inline.DelimiterCount == 3 && inline.DelimiterChar == '%'
                ? "blink"
                : null)
            ?? previousTag(inline);
    }
}
// Fluent API extension method
public static class BlinkExtensionMethods
{
    public static MarkdownPipelineBuilder UseBlink(
        this MarkdownPipelineBuilder pipeline)
    {
        pipeline.Extensions.AddIfNotAlready<BlinkExtension>();
        return pipeline;
    }
}

Usage:

var pipeline = new MarkdownPipelineBuilder()
    .UseBlink()
    .Build();
var html = Markdown.ToHtml("This is %%%blinking%%% text.", pipeline);
// => <p>This is <blink>blinking</blink> text.</p>

Next steps Copy Chapter

- Block parsers — How to write custom block parsers from scratch
- Inline parsers — How to write custom inline parsers
- Renderers — How to create HTML or custom renderers

---

Site/Docs/Advanced/Inline Parsers Copy Section

---
title: Inline parsers
---

Inline parsers

Inline parsers identify inline-level elements (emphasis, links, code spans, custom syntax, etc.) from the text content of LeafBlock nodes. They run during the second phase of parsing, after all blocks have been identified.

How inline parsing works Copy Chapter

After block parsing produces a tree of blocks, the InlineProcessor visits every LeafBlock and processes its text:

1. Walk through the text character by character.
2. At each position, check if any InlineParser has that character in its OpeningCharacters.
3. Call Match on matching parsers (in priority order) until one returns true.
4. If a parser matches, add the created inline to the current container.
5. If no parser matches, the LiteralInlineParser consumes the character into a LiteralInline.
6. After all text is consumed, run post-processing (e.g., emphasis restructuring).

The InlineParser base class Copy Chapter

public abstract class InlineParser : ParserBase<InlineProcessor>, IInlineParser<InlineProcessor>
{
    // Characters that trigger this parser
    public char[]? OpeningCharacters { get; set; }
    // Try to match an inline at the current position
    public abstract bool Match(InlineProcessor processor, ref StringSlice slice);
}

The interface is deliberately simple: set OpeningCharacters and implement Match.

Writing a custom inline parser Copy Chapter

Step 1: Define the AST node Copy Section

Create a class inheriting from LeafInline (for simple inlines) or ContainerInline (for inlines that contain other inlines):

using Markdig.Syntax.Inlines;
/// <summary>
/// An inline representing a keyboard shortcut: [[Ctrl+S]]
/// </summary>
public class KeyboardInline : LeafInline
{
    /// <summary>
    /// The keyboard shortcut text.
    /// </summary>
    public string? Shortcut { get; set; }
}

Step 2: Implement the inline parser Copy Section

/ Detailed source-code truncated for AI context efficiency. /

Step 3: Key points about Match Copy Section

- Return false if no match — Don't advance the slice if you don't match.
- Set processor.Inline — This is how you return the matched inline to the processor.
- Advance slice.Start — Move past the consumed characters. Other parsers will see text starting from the new position.
- Set source position — Use processor.GetSourcePosition for accurate Span, Line, and Column.

Working with StringSlice Copy Chapter

The slice parameter is a mutable view into the LeafBlock's text. Key operations:

{.table}
| Member | Description |
|---|---|
| slice.CurrentChar | Character at current position |
| slice.PeekChar(offset) | Look ahead without advancing |
| slice.NextChar() | Advance and return the next character |
| slice.SkipChar() | Skip one character |
| slice.Start | Start index (mutable — advance this to consume) |
| slice.End | End index |
| slice.Text | The underlying string |
| slice.IsEmpty | True if Start > End |

The InlineProcessor Copy Chapter

Inside Match, the processor provides context:

{.table}
| Member | Description |
|---|---|
| processor.Inline | Set this to your created inline on match |
| processor.Block | The LeafBlock currently being processed |
| processor.Root | The root ContainerInline of the current block |
| processor.Document | The root MarkdownDocument |
| processor.Context | The per-call MarkdownParserContext (may be null) |
| processor.GetSourcePosition(pos, out line, out column) | Map a slice position to source position |
| processor.GetParserState<TState>(this) | Get/create parser state scoped to the current leaf processing pass |
| processor.Emit(inline) | Append inline into the deepest open inline container and set processor.Inline |
| processor.BlockNew | Request replacing the current leaf block after inline processing completes |
| processor.ReplaceParentContainer(old, @new) | Advanced: synchronize traversal if you replace a parent container block during inline processing |

Container inlines and delimiters Copy Chapter

Some inline syntaxes are paired delimiters: they open, later close, and the content between them becomes children of a ContainerInline node.

Markdig implements this pattern with temporary delimiter nodes (subclasses of DelimiterInline) plus a post-processing step that rewires the inline linked-list into the final AST shape.

Before building your own delimiter system, consider:

- If your syntax can be expressed as a simple paired delimiter (~~, ==, ^^, ""..."", etc.), prefer extending EmphasisInlineParser by adding an EmphasisDescriptor. This gives you correct nesting rules and integrates with existing HTML renderers.
- If you need custom pairing rules (like links/images, tables, or non-trivial delimiter constraints), follow the built-in patterns:
- EmphasisInlineParser + EmphasisDelimiterInline
- LinkInlineParser + LinkDelimiterInline
- PipeTableDelimiterInline (tables)

Post-processing with IPostInlineProcessor Copy Chapter

For complex inlines that need restructuring after all inline parsing is complete, implement IPostInlineProcessor:

public interface IPostInlineProcessor
{
    bool PostProcess(
        InlineProcessor state,
        Inline? root,
        Inline? lastChild,
        int postInlineProcessorIndex,
        bool isFinalProcessing);
}

The emphasis system uses this to restructure nested delimiter runs into properly ordered EmphasisInline nodes.

Inline manipulation helpers Copy Chapter

When post-processing, use these helper methods on Inline:

{.table}
| Method | Description |
|---|---|
| InsertAfter(inline) | Insert a new inline after this one in the parent |
| InsertBefore(inline) | Insert before this one |
| Remove() | Remove this inline from its parent |
| ReplaceBy(newInline) | Replace this inline with another, optionally moving children |
| PreviousSibling | Previous sibling in the linked list |
| NextSibling | Next sibling |
| FirstParentOfType<T>() | Find the nearest ancestor of type T |

Example: simple emoji parser Copy Chapter

A complete inline parser that converts :name: shortcodes:

public class SimpleEmojiParser : InlineParser
{
    private readonly Dictionary<string, string> _emojis = new()
    {
        { "smile", "😊" },
        { "heart", "❤️" },
        { "rocket", "🚀" }
    };
    public SimpleEmojiParser()
    {
        OpeningCharacters = [':'];
    }
    public override bool Match(InlineProcessor processor, ref StringSlice slice)
    {
        var start = slice.Start;
        // Skip opening ':'
        var c = slice.NextChar();
        // Read the emoji name
        var nameStart = slice.Start;
        while (c != ':' && c != '\0' && !c.IsWhitespace())
        {
            c = slice.NextChar();
        }
        if (c != ':')
        {
            // No closing ':', reset and fail
            slice.Start = start;
            return false;
        }
        var name = slice.Text[nameStart..slice.Start];
        if (!_emojis.TryGetValue(name, out var emoji))
        {
            slice.Start = start;
            return false;
        }
        // Skip closing ':'
        slice.NextChar();
        processor.Inline = new LiteralInline(emoji)
        {
            Span = new SourceSpan(
                processor.GetSourcePosition(start, out int line, out int column),
                processor.GetSourcePosition(slice.Start - 1, out _, out _)),
            Line = line,
            Column = column
        };
        return true;
    }
}

Next steps Copy Chapter

- Block parsers — Write block-level parsers
- Renderers — Create renderers for your custom inlines
- Creating extensions — Wire parsers and renderers into an extension

---

Site/Docs/Advanced/Parser Authoring Api Copy Section

---
title: Parser authoring API
---

Parser + AST authoring API

This page documents parser authoring contracts and the public APIs intended to give third-party extensions parity with built-in extensions (and to make safe AST manipulation less error-prone).

If you're new to writing extensions, start with Creating extensions and then come back here for the "engine contract" details.

Scope Copy Chapter

The authoring model remains two-phase:

1. Block parsing (BlockProcessor + BlockParser).
2. Inline parsing (InlineProcessor + InlineParser + IPostInlineProcessor).

Performance characteristics are unchanged: parser dispatch still relies on opening-character maps and pooled processors.

Public API Additions Copy Chapter

InlineProcessor.ReplaceParentContainer(...) ')" title="Copy section prompt for LLMs"> Copy Section

Use this when an inline parser replaces a parent container block during inline processing.

Contract:

- Call only while processing the current leaf (ProcessInlineLeaf pass).
- Replace the container in the AST first, then call ReplaceParentContainer(old, @new) to synchronize traversal state.
- Only one replacement request is allowed per leaf processing pass.

BlockProcessor.TakeLinesBefore() ')" title="Copy section prompt for LLMs"> Copy Section

Use this in TryOpen when TrackTrivia is enabled and the new block should own pending leading blank/trivia lines.

Contract:

- Returns current LinesBefore and clears it.
- Returns null when there is no pending list.

BlockProcessor.IsOpen(Block) and BlockProcessor.TryDiscard(Block) and BlockProcessor.TryDiscard(Block)')" title="Copy section prompt for LLMs"> Copy Section

Use these to safely reason about/modify the open block stack.

Contract:

- IsOpen is a read-only stack membership check.
- TryDiscard removes an open non-root block from both parent container and open stack, returning true only when a discard happened.

MarkdownPipelineBuilder.TrackTrivia ')" title="Copy section prompt for LLMs"> Copy Section

TrackTrivia is now publicly settable and flows into the built pipeline/processors.

Block Parser Contract Copy Chapter

BlockState semantics semantics')" title="Copy section prompt for LLMs"> Copy Section

- None: no match for this parser/block.
- Skip: skip parser for this line and continue with others.
- Continue: block stays open; leaf blocks append line content.
- ContinueDiscard: block stays open; line consumed but not appended.
- Break: block closes; current line remains available for further parsing.
- BreakDiscard: block closes; current line is consumed.

NewBlocks invariants invariants')" title="Copy section prompt for LLMs"> Copy Section

- Every pushed block must have Parser set to the creating parser.
- Leaf blocks must be pushed last.
- Push order is outer container to inner container to leaf (LIFO pop in processor).

Trivia rules Copy Section

When TrackTrivia is enabled:

- Use TakeLinesBefore() in TryOpen to assign pending leading blank/trivia lines.
- Use UseTrivia(end) when a parser needs exact trivia slices around syntax markers.

Inline Parser Contract Copy Chapter

Match behavior behavior')" title="Copy section prompt for LLMs"> Copy Section

- On success: advance slice and set processor.Inline when emitting a node.
- On failure: return false without mutating parser output state.

Emission behavior Copy Section

- If a matched parser sets a parentless processor.Inline, the processor appends it to the deepest open inline container.
- For explicit emission, use processor.Emit(inline).

Parser state Copy Section

Use processor.GetParserState<TState>(this) or processor.GetParserState(this, factory) for per-leaf parser state.
Parser states are cleared at the beginning of each ProcessInlineLeaf.

Block transforms from inline parsing Copy Section

- processor.BlockNew replaces the current leaf block after the current leaf pass returns.
- processor.ReplaceParentContainer(old, @new) keeps traversal coherent when a parent container has already been replaced in the AST.

Hook Selection Copy Chapter

| Goal | Preferred hook |
|---|---|
| Add block syntax | BlockParser in MarkdownPipelineBuilder.BlockParsers |
| Add inline syntax | InlineParser in MarkdownPipelineBuilder.InlineParsers |
| Deferred inline resolution | IPostInlineProcessor |
| Replace current leaf block | InlineProcessor.BlockNew |
| Replace parent container from inline | InlineProcessor.ReplaceParentContainer |
| Literal post-processing | LiteralInlineParser.PostMatch |
| Post-close block transform | BlockParser.Closed |
| Per-block inline begin/end behavior | Block.ProcessInlinesBegin / Block.ProcessInlinesEnd |
| Post-document transform | MarkdownPipelineBuilder.DocumentProcessed |

AST Mutation Helpers Copy Chapter

Block-level Copy Section

- Block.Remove(): remove from parent container.
- Block.ReplaceBy(replacement, moveChildren: true): replace in parent container and optionally move children.
- ContainerBlock.TransferChildrenTo(destination): move child blocks in order.

Inline-level Copy Section

- ContainerInline.TransferChildrenTo(destination): move child inlines in order.

Mutation helpers do not auto-recompute spans/trivia; callsites remain responsible for source metadata correctness when required.

Typed Metadata Helpers Copy Chapter

For extension state attached to AST nodes:

- SetData<T>(value) / GetData<T>().
- TryGetData<T>(key, out value) / GetData<T>(key) for explicit object keys.
- DataKey<T> for collision-resistant typed keys.

Example:

var key = new DataKey<MyState>();
block.SetData<MyState>(key, state);
if (block.TryGetData<MyState>(key, out var existing))
{
    // use existing
}

---

Site/Docs/Advanced/Parser Authoring Api Migration Copy Section

---
title: Parser authoring API migration notes
---

Parser + AST API migration notes (potential breaking changes)

This document tracks compatibility risks for consumers adopting the new parser/AST authoring APIs and for future releases that may tighten contracts.

Current Release Impact Copy Chapter

The implemented changes are additive/public-surface expansions:

- InlineProcessor.ReplaceParentContainer(...) is now public.
- BlockProcessor.TakeLinesBefore() is public.
- BlockProcessor.IsOpen(Block) is public.
- BlockProcessor.TryDiscard(Block) is new.
- InlineProcessor.GetParserState(...) and InlineProcessor.Emit(...) are new.
- Block.Remove(), Block.ReplaceBy(...), ContainerBlock.TransferChildrenTo(...), and ContainerInline.TransferChildrenTo(...) are new.
- MarkdownPipelineBuilder.TrackTrivia setter is public.
- Typed metadata helpers (DataKey<T>, MarkdownObjectDataExtensions) are new.

No runtime behavior change is required for existing consumers unless they opt into these APIs.

Potential Future Breaking Changes Copy Chapter

These are not implemented in this release, but consumers should avoid relying on ambiguous behavior.

1. ReplaceParentContainer replacement limits replacement limits')" title="Copy section prompt for LLMs"> Copy Section

Current contract allows a single replacement request per leaf pass. If this evolves to support multiple requests, error behavior and ordering guarantees may change.

Guidance:

- Keep replacements localized and deterministic.
- Avoid depending on repeated replacement attempts in one pass.

2. Mutation-helper metadata behavior Copy Section

Mutation helpers currently do not recalculate spans/trivia automatically. A future strict mode might validate or enforce metadata consistency.

Guidance:

- Explicitly set/update Span, Line, Column, and trivia fields in transforms where source fidelity matters.

3. Internal helper cleanup Copy Section

Internal compatibility shims may be removed in a later major release after migration (for example, internal aliases kept during transition).

Guidance:

- Use public methods (TakeLinesBefore, TryDiscard, etc.) directly.

4. Typed metadata API naming and overload resolution Copy Section

Some helper overloads share names with existing instance methods. Advanced consumers should prefer explicit generic invocations to avoid ambiguity.

Guidance:

- Prefer explicit generic calls:
- node.SetData<MyType>(value)
- node.SetData<MyType>(key, value)
- node.GetData<MyType>(key)
- node.TryGetData<MyType>(key, out var value)

Migration Checklist for Extension Authors Copy Chapter

1. Replace custom open-stack discard patterns with TryDiscard where appropriate.
2. Use TakeLinesBefore() instead of internal trivia helpers.
3. For inline-driven parent replacement:
- replace the parent container in the AST first,
- then call ReplaceParentContainer(old, @new).
4. Replace manual child-move loops (RemoveAt(0) patterns) with transfer helpers.
5. Add regression tests for transformed AST shape (parent/child ownership and ordering).

Versioning Guidance Copy Chapter

For a future major version, consider:

- deprecating internal transition shims,
- optionally adding strict validation mode for parser invariants and mutation metadata,
- documenting any tightened contracts as migration steps in this file.

---

Site/Docs/Advanced/Performance Copy Section

---
title: Performance
---

Performance

Markdig is designed for high throughput and low allocations. This page covers the patterns used internally and recommendations for extension authors.

Allocation-free parsing Copy Chapter

StringSlice Copy Section

The core parsing type is StringSlice — a struct that holds a reference to a string plus start/end indices:

public struct StringSlice
{
    public string? Text;
    public int Start;
    public int End;
    public readonly char CurrentChar => Start <= End ? Text![Start] : '\0';
    public readonly int Length => End - Start + 1;
}

All parsers work on StringSlice rather than allocating substrings. When writing parsers, always use StringSlice methods:

{.table}
| Instead of | Use |
|---|---|
| text.Substring(...) | slice.ToString() (only when you need a string) |
| text[i] | slice.PeekCharExtra(offset) |
| text.Trim() | slice.Trim() (mutates the struct) |
| text.IndexOf(c) | slice.IndexOf(c) |

ReadOnlySpan<char> Copy Section

For hot paths, prefer ReadOnlySpan<char> over string:

// Good — no allocation
ReadOnlySpan<char> span = slice.AsSpan();
if (span.StartsWith("

// Avoid — allocates a string
string text = slice.ToString();
if (text.StartsWith("`"))
{
// ...
}


stackalloc  Copy Section
For small temporary buffers, use stackalloc:

ArrayPool  Copy Section
For larger buffers, use ArrayPool<T>:

Pipeline and renderer reuse  Copy Chapter
Build once, use many times  Copy Section
The MarkdownPipeline is immutable and thread-safe after Build(). Always cache it:

Renderer pooling  Copy Section
Markdown.ToHtml and friends internally pool HtmlRenderer instances. If you create renderers manually, consider pooling them:

Extension authoring tips  Copy Chapter
Use sealed classes  Copy Section
Mark classes as sealed when they're not designed for inheritance. This allows the JIT to devirtualize method calls:

Prefer struct over class for small types  Copy Section
For data-only types that are short-lived, prefer struct:

Avoid LINQ in hot paths  Copy Section
LINQ allocates enumerator objects. In parser code, prefer for/foreach loops:

Minimize string concatenation  Copy Section
Use StringBuilder or the renderer's built-in Write chaining:

Cache frequently used strings  Copy Section
For attribute names and CSS classes that repeat:

AOT and trimming compatibility  Copy Chapter
Markdig is designed to be compatible with Native AOT and IL trimming.
Avoid reflection  Copy Section
Do not use Type.GetMethod(), Activator.CreateInstance(), or similar reflection APIs in parsers and renderers:

Use source generators when applicable  Copy Section
For serialization scenarios, prefer source generators over reflection-based serialization:

Annotate when reflection is unavoidable  Copy Section
If you must use reflection, annotate with [DynamicallyAccessedMembers]:

Benchmarking  Copy Chapter
Markdig includes a benchmarks project for measuring performance:

The benchmarks compare Markdig against other .NET Markdown processors using BenchmarkDotNet.
To benchmark your extension, add a test case to the benchmarks project:

Summary of recommendations  Copy Chapter
{.table}
| Area | Recommendation |
|---|---|
| String handling | Use StringSlice and ReadOnlySpan<char>; avoid Substring |
| Buffers | stackalloc for small; ArrayPool<T> for large |
| Pipeline | Build once, pass everywhere, reuse across threads |
| Classes | sealed by default; struct for small data types |
| Loops | for/foreach over LINQ in parsers |
| Output | Chain Write calls; avoid string interpolation in renderers |
| AOT | No reflection; use source generators; annotate if unavoidable |
| Verify | Run benchmarks before/after changes |
---
Site/Docs/Advanced/Pipeline  Copy Section
---
title: Pipeline architecture
---
Pipeline architecture
This guide explains how the MarkdownPipeline works, how extensions configure it, and how the parsing flow proceeds from source text to AST to rendered output.
Overview  Copy Chapter
Markdig's processing involves three objects:
1. MarkdownPipelineBuilder — A mutable builder where you configure extensions, parsers, and options.
2. MarkdownPipeline — An immutable, thread-safe object produced by the builder. Contains the final parser and extension lists.
3. Markdown — The static class that uses a pipeline to parse and render.

NOTE
MarkdownPipelineBuilder is mutable and not thread-safe. Build pipelines during configuration/startup, then share the built MarkdownPipeline instances.
What the pipeline holds  Copy Chapter
The MarkdownPipeline contains:
{.table}
| Component | Type | Description |
|---|---|---|
| Block parsers | BlockParserList | Ordered list of BlockParser objects |
| Inline parsers | InlineParserList | Ordered list of InlineParser objects |
| Extensions | OrderedList<IMarkdownExtension> | Registered extensions |
| TrackTrivia | bool | Whether trivia parsing is enabled |
| MaximumNestingDepth | int | Maximum AST nesting depth allowed while parsing and rendering |
| DocumentProcessed | ProcessDocumentDelegate? | Callback after parsing completes |
Nesting depth limit  Copy Chapter
Markdig protects parsing and rendering with a conservative default nesting limit of 128 levels. If you process trusted input that can legitimately produce deeper trees, configure MaximumNestingDepth before calling Build():

Only raise this for trusted content: a larger limit allows deeper documents but can increase parsing cost and rendering stack usage.
How Build() works  Copy Chapter
When you call builder.Build():
1. Each registered extension's Setup(MarkdownPipelineBuilder) method is called in order.
2. Extensions may add/remove/modify block parsers, inline parsers, or other settings.
3. The builder's mutable state is frozen into an immutable MarkdownPipeline.
4. The builder caches the result — calling Build() again returns the same instance.
This is why extension ordering matters: an extension may look for parsers added by a previous extension.
How Parse() works  Copy Chapter
Markdown.Parse(string, pipeline) executes these steps:
Step 1: Block parsing  Copy Section
A BlockProcessor is created with the pipeline's block parsers. It processes the source text line by line:
1. For each line, the processor checks all open blocks to see if they continue (TryContinue).
2. Blocks that don't continue are closed.
3. The processor tries each BlockParser to see if a new block opens at the current position (TryOpen).
4. Characters are dispatched based on OpeningCharacters — parsers are only tried when their opening character matches.
The result is a tree of Block nodes rooted at the MarkdownDocument.
Step 2: Trivia expansion (optional)  Copy Section
If TrackTrivia is enabled, blocks are expanded to absorb neighboring whitespace and trivia. This supports lossless roundtripping.
Step 3: Inline parsing  Copy Section
An InlineProcessor visits each LeafBlock and runs the pipeline's inline parsers over the block's text content:
1. Starting from the first character, the processor finds InlineParser objects whose OpeningCharacters match.
2. The Match method is called on each candidate parser (in order) until one returns true.
3. The matched inline is added to the block's Inline container.
4. If no parser matches, a LiteralInlineParser consumes the character.
5. After all characters are consumed, post-processing runs (e.g., emphasis restructuring).
Step 4: Post-processing  Copy Section
The DocumentProcessed delegate (if set) is invoked on the completed document.
Step 5: Return  Copy Section
The MarkdownDocument is returned.
How rendering works  Copy Chapter
Rendering is a separate phase. When you call document.ToHtml(pipeline):
1. An HtmlRenderer is created (or borrowed from a pool).
2. pipeline.Setup(renderer) is called — this invokes Setup(MarkdownPipeline, IMarkdownRenderer) on every registered extension, giving each one the chance to register its ObjectRenderer.
3. The renderer walks the AST, dispatching each node to the appropriate ObjectRenderer by type.
4. The rendered output is returned.
IMPORTANT
This is why the same pipeline must be used for both parsing and rendering. The parse-phase Setup registers parsers that produce custom AST node types. The render-phase Setup registers renderers that know how to output those types. Mismatched pipelines = missing renderers.
Extension setup: two phases  Copy Chapter
Every IMarkdownExtension has two Setup methods:

Phase 1 example  Copy Section

Phase 2 example  Copy Section

The OrderedList<T> collection  Copy Chapter
Both parser and extension lists are OrderedList<T>, a custom Markdig collection with methods for type-safe insertion:
{.table}
| Method | Description |
|---|---|
| AddIfNotAlready<T>() | Add if no instance of T exists |
| InsertBefore<TBefore>(item) | Insert before a specific type |
| InsertAfter<TAfter>(item) | Insert after a specific type |
| Find<T>() | Find the first instance of type T |
| FindExact<T>() | Find an exact type match (not subclasses) |
| TryFind<T>(out T?) | Try to find, returning success |
| Replace<T>(newItem) | Replace an existing item of type T |
| ReplaceOrAdd<T>(newItem) | Replace or add if not found |
| TryRemove<T>() | Remove the first instance of type T |
| Contains<T>() | Check if an instance of type T exists |
Default parsers  Copy Chapter
Without any extensions, the pipeline contains these parsers:
Default block parsers  Copy Section
1. ThematicBreakParser
2. HeadingBlockParser
3. QuoteBlockParser
4. ListBlockParser
5. HtmlBlockParser
6. FencedCodeBlockParser
7. IndentedCodeBlockParser
8. ParagraphBlockParser
Default inline parsers  Copy Section
1. HtmlEntityParser
2. LinkInlineParser
3. EscapeInlineParser
4. EmphasisInlineParser
5. CodeInlineParser
6. AutolinkInlineParser
7. LineBreakInlineParser
Extensions add to or modify these lists.
Trivia and roundtripping  Copy Chapter
Enable trivia tracking for lossless parse→render roundtrips:

When trivia is tracked, whitespace, extra heading characters, and other non-semantic elements are stored on the AST nodes, allowing the document to be re-rendered as close to the original as possible.
---
Site/Docs/Advanced/Readme  Copy Section
---
title: Developer guide
---
Developer guide
Markdig is designed to be deeply extensible. This guide covers how the parsing pipeline works, how to traverse and manipulate the AST, and how to create your own extensions with custom block parsers, inline parsers, and renderers.
Architecture overview  Copy Chapter
Markdig's processing flow has three stages:

1. Block parsing — The BlockProcessor walks through the source text line by line, using registered BlockParser objects to identify block-level elements (paragraphs, headings, lists, code blocks, etc.) and build the AST skeleton.
2. Inline parsing — The InlineProcessor visits every LeafBlock in the AST and runs registered InlineParser objects over the block's text to identify inline elements (emphasis, links, code spans, etc.).
3. Rendering — A renderer (typically HtmlRenderer) walks the complete AST and dispatches each node to a matching ObjectRenderer for output.
Extensions can modify any of these stages: adding new parsers, modifying existing ones, or registering custom renderers.
Guides  Copy Chapter
{.table}
| Guide | What you'll learn |
|---|---|
| Abstract syntax tree | Structure of block/inline nodes, traversal with Descendants, source spans |
| Pipeline architecture | How MarkdownPipeline, MarkdownPipelineBuilder, and extensions interact |
| Creating extensions | Implement IMarkdownExtension — from simple to complex |
| Parser authoring API | Authoring contracts and advanced APIs for parser/AST parity |
| Block parsers | Write custom BlockParser subclasses — TryOpen, TryContinue, BlockState |
| Inline parsers | Write custom InlineParser subclasses — Match, StringSlice, post-processing |
| Renderers | Implement HtmlObjectRenderer<T> or build a completely custom renderer |
| Performance | Tips for maintaining high throughput — allocation-free patterns, pooling, Span-based parsing |
| Migration notes | Compatibility risks and future contract tightening to avoid depending on ambiguous behavior |
Quick reference: key types  Copy Chapter
{.table}
| Type | Role |
|---|---|
| Markdown | Static entry point — Parse, ToHtml, Convert |
| MarkdownPipeline | Immutable, thread-safe configuration object |
| MarkdownPipelineBuilder | Fluent builder for MarkdownPipeline |
| IMarkdownExtension | Interface all extensions implement |
| BlockParser | Abstract base for block-level parsers |
| InlineParser | Abstract base for inline-level parsers |
| MarkdownDocument | Root AST node (a ContainerBlock) |
| Block | Base for all block AST nodes |
| Inline | Base for all inline AST nodes |
| MarkdownObject | Base for all AST nodes — provides Span, Line, Column, data storage |
| HtmlRenderer | Built-in HTML output renderer |
| HtmlObjectRenderer<T> | Base for per-type HTML rendering |
| IMarkdownRenderer | Interface for custom renderers |
---
Site/Docs/Advanced/Renderers  Copy Section
---
title: Renderers
---
Renderers
Renderers walk the AST and produce output. Markdig ships with an HtmlRenderer (HTML output), a NormalizeRenderer (canonical Markdown output), and supports fully custom renderers for any output format.
How rendering works  Copy Chapter
When you call document.ToHtml(pipeline):
1. An HtmlRenderer is created (internally pooled for performance).
2. pipeline.Setup(renderer) is called — each extension's Setup(MarkdownPipeline, IMarkdownRenderer) runs, registering per-type ObjectRenderers.
3. The renderer walks the AST depth-first, dispatching each node to the ObjectRenderer registered for its runtime type.
4. Output is written to the underlying TextWriter.
The IMarkdownRenderer interface  Copy Chapter

HTML renderers  Copy Chapter
HtmlObjectRenderer<T>  Copy Section
The most common way to render custom AST nodes to HTML is to create a class inheriting from HtmlObjectRenderer<T>:

The generic parameter T automatically registers this renderer for all NoteBlock nodes.
HtmlRenderer write methods  Copy Section
The HtmlRenderer provides these commonly used methods:
{.table}
| Method | Description |
|---|---|
| Write(string) | Write raw text |
| Write(char) | Write a single character |
| WriteEscape(string) | Write HTML-escaped text |
| WriteEscape(StringSlice) | Write HTML-escaped slice |
| WriteLeafInline(LeafBlock) | Render all inlines of a leaf block |
| WriteLeafRawLines(LeafBlock) | Write raw line content (for code blocks) |
| WriteAttributes(MarkdownObject) | Write attached HTML attributes |
| WriteLine() | Write a newline |
| EnsureLine() | Write a newline only if not already at line start |
| PushIndent(string) | Push indentation for nested content |
| PopIndent() | Pop indentation |
Writing container blocks  Copy Section
For custom ContainerBlock nodes, render children with WriteChildren:

Writing inline renderers  Copy Section
For custom Inline nodes:

Rendering container inlines  Copy Section
For ContainerInline types, render children inline:

Registering renderers  Copy Chapter
Renderers are registered in the extension's Setup(MarkdownPipeline, IMarkdownRenderer) method:

Insertion ordering  Copy Section
Like parsers, renderers can be inserted at specific positions:

Modifying existing renderers  Copy Chapter
You can modify built-in renderers without replacing them:

HtmlRenderer properties  Copy Chapter
The HtmlRenderer has several useful properties:
{.table}
| Property | Type | Default | Description |
|---|---|---|---|
| EnableHtmlForInline | bool | true | Emit HTML tags for inlines |
| EnableHtmlForBlock | bool | true | Emit HTML tags for blocks |
| EnableHtmlEscape | bool | true | HTML-escape special characters |
When all three are false, the renderer produces plain text — this is how Markdown.ToPlainText works.
Events: Before and After  Copy Chapter
You can hook into the rendering pipeline with events:

Building a completely custom renderer  Copy Chapter
For non-HTML output (LaTeX, XAML, JSON, etc.), you can implement a full custom renderer:
Option 1: Inherit TextRendererBase  Copy Section
For text-based output formats:

Option 2: Implement IMarkdownRenderer directly  Copy Section
For fully custom output (JSON, binary, etc.):

Using custom renderers  Copy Section
Pass your renderer to Markdown.Convert:

Complete example: rendering NoteBlock  Copy Chapter
Putting it all together — the block parser, renderer, and extension:

Usage:

Next steps  Copy Chapter
- Block parsers — Write the parsers that produce custom AST nodes
- Inline parsers — Write inline-level parsers
- Performance — Optimize rendering performance
---
Site/Docs/Extensions/Abbreviations  Copy Section
---
title: Abbreviations
---
Abbreviations
Enable with .UseAbbreviations() (included in UseAdvancedExtensions()).
Abbreviations define expansions for acronyms and short terms. When the abbreviation appears in the text, it is wrapped in an <abbr> tag with a title attribute. Inspired by PHP Markdown Extra.
Syntax  Copy Chapter
Define abbreviations anywhere in the document using *[ABBR]: Full text:

*[HTML]: Hyper Text Markup Language
*[CSS]: Cascading Style Sheets
This page uses HTML and CSS.
HTML output  Copy Chapter

Rules  Copy Chapter
- Abbreviation definitions are not rendered as visible content.
- Matching is case-sensitive and matches whole words only.
- Abbreviation definitions can appear anywhere in the document — they apply globally.
- Multiple abbreviations can be defined in the same document.
---
Site/Docs/Extensions/Alert Blocks  Copy Section
---
title: Alert blocks
---
Alert blocks
Enable with .UseAlertBlocks() (included in UseAdvancedExtensions()).
Alert blocks are GitHub-style callouts for highlighting important content in documentation. They are rendered as styled <div> elements.
Syntax  Copy Chapter
Alert blocks are blockquotes that begin with a special [!TYPE] marker:

NOTE
Useful information that users should know, even when skimming content.
TIP
Helpful advice for doing things better or more easily.
IMPORTANT
Key information users need to know to achieve their goal.
WARNING
Urgent info that needs immediate user attention to avoid problems.
CAUTION
Advises about risks or negative outcomes of certain actions.
Alert types  Copy Chapter
{.table}
| Type | Purpose |
|---|---|
| [!NOTE] | Supplementary information |
| [!TIP] | Helpful suggestions |
| [!IMPORTANT] | Critical information |
| [!WARNING] | Potential problems |
| [!CAUTION] | Risk of negative outcomes |
HTML output  Copy Chapter
Each alert renders as:

The markdown-alert-{type} CSS class allows you to apply custom styling for each alert kind.
Content within alerts  Copy Chapter
Alerts support full Markdown content — paragraphs, lists, code blocks, emphasis, etc.:

> `csharp

`

TIP
You can use bold, italic, and code in alerts.

> - Even lists work

- Inside alert blocks

>

`

Custom rendering Copy Chapter

Pass a custom renderer delegate to UseAlertBlocks to override the kind rendering:

var pipeline = new MarkdownPipelineBuilder()
    .UseAlertBlocks(renderKind: (renderer, kind) =>
    {
        renderer.Write($"<span class=\"icon\">{kind}</span>");
    })
    .Build();

---

Site/Docs/Extensions/Auto Identifiers Copy Section

---
title: Auto-identifiers
---

Auto-identifiers

Enable with .UseAutoIdentifiers() (included in UseAdvancedExtensions()).

This extension automatically generates id attributes for all headings, similar to Pandoc auto identifiers. This is essential for linking to specific sections.

How it works Copy Chapter

Every heading gets an id attribute derived from its text content:

Getting Started  Copy Chapter

Renders as:

<h2 id="getting-started">Getting Started</h2>

You can then link to it:

See Getting Started.

ID generation rules Copy Chapter

1. Convert to lowercase
2. Remove anything that is not a letter, number, space, or hyphen
3. Replace spaces with hyphens
4. Remove leading/trailing hyphens

Examples:

{.table}
| Heading | Generated ID |
|---|---|
| # Hello World | hello-world |
| ## C# Tips & Tricks | c-tips--tricks |
| ### 2. Installation | 2-installation |

Duplicate handling Copy Chapter

If two headings produce the same ID, a numeric suffix is appended:

Section  Copy Chapter

Section  Copy Chapter

Section  Copy Chapter

Produces: section, section-1, section-2.

Options Copy Chapter

UseAutoIdentifiers accepts an AutoIdentifierOptions flags enum:

using Markdig.Extensions.AutoIdentifiers;
var pipeline = new MarkdownPipelineBuilder()
    .UseAutoIdentifiers(AutoIdentifierOptions.GitHub)
    .Build();

Available options:

{.table}
| Option | Description |
|---|---|
| AutoIdentifierOptions.Default | Standard auto-identifier behavior |
| AutoIdentifierOptions.GitHub | GitHub-compatible ID generation |
| AutoIdentifierOptions.AutoLink | Also create a self-link anchor |
| AutoIdentifierOptions.AllowOnlyAscii | Strip non-ASCII characters from IDs |

Combining with generic attributes Copy Chapter

You can override the auto-generated ID using Generic attributes:

My Heading {#custom-id}  Copy Chapter

The explicit #custom-id takes precedence over the auto-generated one.

---

Site/Docs/Extensions/Auto Links Copy Section

---
title: Auto-links
---

Auto-links

Enable with .UseAutoLinks() (included in UseAdvancedExtensions()).

This extension automatically detects URLs and email addresses in plain text and converts them into clickable links — no angle brackets or explicit Markdown link syntax required.

Detected patterns Copy Chapter

URLs starting with these protocols are detected automatically:

- http://
- https://
- ftp://
- mailto:
- www. (rendered as http://www.)

Check out https://github.com/xoofx/markdig for more info.
Visit www.example.com for details.
Contact [email protected] for help.

Check out https://github.com/xoofx/markdig for more info.

Visit www.example.com for details.

HTML output Copy Chapter

<p>Check out <a href="https://github.com/xoofx/markdig">https://github.com/xoofx/markdig</a> for more info.</p>

Options Copy Chapter

UseAutoLinks accepts an AutoLinkOptions object:

using Markdig.Extensions.AutoLinks;
var pipeline = new MarkdownPipelineBuilder()
    .UseAutoLinks(new AutoLinkOptions
    {
        OpenInNewWindow = true,  // Add target="_blank"
        UseHttpsForWWWLinks = true // www. links become https:// instead of http://
    })
    .Build();

Difference from CommonMark autolinks Copy Chapter

CommonMark already supports angle-bracket autolinks (<https://example.com>). This extension goes further by detecting bare URLs without any markers.

---

Site/Docs/Extensions/Cjk Friendly Emphasis Copy Section

---
title: CJK friendly emphasis
---

CJK friendly emphasis

Enable with .UseCjkFriendlyEmphasis() (not included in UseAdvancedExtensions()).

This extension adjusts emphasis delimiter rules to better support Chinese/Japanese/Korean (CJK) text, where words are commonly written without spaces. It follows the markdown-cjk-friendly specification and mitigates the CommonMark emphasis limitation discussed in commonmark-spec#650.

Enable Copy Chapter

using Markdig;
var pipeline = new MarkdownPipelineBuilder()
    .UseCjkFriendlyEmphasis()
    .Build();

You can also enable it via string configuration:

var pipeline = new MarkdownPipelineBuilder()
    .Configure("common+cjk-friendly-emphasis")
    .Build();

Examples Copy Chapter

Some emphasis sequences that often fail with plain CommonMark in CJK text become parseable with this extension enabled:

この文を強調できますか？残念ながらできません。
我可以强调这个code吗？
이 용어(This term)를 강조해 주세요.

Notes Copy Chapter

- This extension intentionally deviates from strict CommonMark emphasis behavior to improve real-world CJK authoring.
- It only affects how emphasis delimiters are interpreted; it does not add new syntax.

---

Site/Docs/Extensions/Custom Containers Copy Section

---
title: Custom containers
---

Custom containers

Enable with .UseCustomContainers() (included in UseAdvancedExtensions()).

Custom containers generate <div> elements from fenced ::: blocks, similar to how fenced code blocks work. They are inspired by this CommonMark discussion.

Block containers Copy Chapter

Use ::: to open and close a container block:

::: warning
This is a warning container. You can put any Markdown content here.
- Including lists
- And other blocks
:::

::: warning
This is a warning container. You can put any Markdown content here.

- Including lists
- And other blocks
:::

HTML output Copy Section

<div class="warning">
  <p>This is a warning container...</p>
</div>

The text after ::: becomes the CSS class of the <div>.

Inline containers Copy Chapter

Use a single : pair for inline containers:

This has a :custom-span[styled word]{.highlight} in it.

Nesting Copy Chapter

Containers can be nested using more colons:

:::: outer
::: inner
Nested content.
:::
::::

Attributes Copy Chapter

Combine with Generic attributes for full control:

::: {.alert .alert-info #my-alert role="alert"}
This is an informational alert.
:::

This produces:

<div class="alert alert-info" id="my-alert" role="alert">
  <p>This is an informational alert.</p>
</div>

---

Site/Docs/Extensions/Definition Lists Copy Section

---
title: Definition lists
---

Definition lists

Enable with .UseDefinitionLists() (included in UseAdvancedExtensions()).

Definition lists render as <dl> / <dt> / <dd> HTML elements. Inspired by PHP Markdown Extra.

Syntax Copy Chapter

A definition list consists of terms followed by their definitions. Definitions are prefixed with : (colon followed by a space):

Term 1
:   Definition of term 1.
Term 2
:   Definition of term 2.
:   Another definition of term 2.

Term 1
: Definition of term 1.

Term 2
: Definition of term 2.
: Another definition of term 2.

Multi-line definitions Copy Chapter

Definitions can span multiple lines and contain block-level content:

Apple
:   A fruit that grows on trees.
    Apples come in many varieties including
    Granny Smith and Fuji.
Orange
:   A citrus fruit.

Apple
: A fruit that grows on trees.

Apples come in many varieties including
Granny Smith and Fuji.

Orange
: A citrus fruit.

Multiple terms per definition Copy Chapter

Term A
Term B
:   Shared definition for both terms.

Term A
Term B
: Shared definition for both terms.

HTML output Copy Chapter

<dl>
  <dt>Term 1</dt>
  <dd>Definition of term 1.</dd>
  <dt>Term 2</dt>
  <dd>Definition of term 2.</dd>
  <dd>Another definition of term 2.</dd>
</dl>

Rules Copy Chapter

- There must be a blank line before the first term (or it will be treated as a paragraph).
- The : marker must be followed by at least one space.
- Continuation lines must be indented.

---

Site/Docs/Extensions/Diagrams Copy Section

---
title: Diagrams
---

Diagrams

Enable with .UseDiagrams() (included in UseAdvancedExtensions()).

When a fenced code block uses a recognized diagram language as its info string, Markdig renders it as a plain HTML block (without the nested <code> element) so client-side diagram libraries can consume the raw text easily.

By default:

- mermaid renders as a <pre class="mermaid">...</pre> block
- nomnoml renders as a <div class="nomnoml">...</div> block

Supported languages Copy Chapter

{.table}
| Language | Info string |
|---|---|
| Mermaid | mermaid |
| nomnoml | nomnoml |

Mermaid example Copy Chapter

graph LR
    A[Parse] --> B[AST]
    B --> C[Render]
    C --> D[HTML]

<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>mermaid.initialize({ startOnLoad: true });</script>

<pre><code class="language-mermaid">...</code></pre>

<pre class="mermaid">...</pre>
<div class="nomnoml">...</div>

Enable with .UseEmojiAndSmiley() (not included in UseAdvancedExtensions()).

This extension converts emoji shortcodes and (optionally) ASCII smileys into Unicode emoji characters.

Shortcode syntax Copy Section

:smile: :+1: :heart: :rocket: :warning:

Disable smileys Copy Section

By default, ASCII smileys like :) are also converted. To use only named shortcodes:

var pipeline = new MarkdownPipelineBuilder()
    .UseEmojiAndSmiley(enableSmileys: false)
    .Build();

Custom emoji mappings Copy Section

using Markdig.Extensions.Emoji;
var mapping = new EmojiMapping(
    new Dictionary<string, string>
    {
        { ":custom:", "🎉" },
        { ":markdig:", "📝" }
    });
var pipeline = new MarkdownPipelineBuilder()
    .UseEmojiAndSmiley(mapping)
    .Build();

Common shortcodes Copy Section

{.table}
| Shortcode | Emoji |
|---|---|
| :smile: | 😄 |
| :+1: | 👍 |
| :heart: | ❤️ |
| :rocket: | 🚀 |
| :warning: | ⚠️ |
| :star: | ⭐ |
| :fire: | 🔥 |
| :bug: | 🐛 |
| :bulb: | 💡 |
| :memo: | 📝 |

SmartyPants Copy Chapter

Enable with .UseSmartyPants() (not included in UseAdvancedExtensions()).

SmartyPants converts ASCII punctuation into typographically correct HTML entities. Inspired by Daring Fireball — SmartyPants.

Transformations Copy Section

{.table}
| Input | Output | Description |
|---|---|---|
| "Hello" | "Hello" | Smart double quotes |
| 'Hello' | 'Hello' | Smart single quotes |
| -- | – | En dash |
| --- | — | Em dash |
| ... | … | Ellipsis |
| << | « | Left guillemet |
| >> | » | Right guillemet |

Usage Copy Section

var pipeline = new MarkdownPipelineBuilder()
    .UseSmartyPants()
    .Build();
var html = Markdown.ToHtml("He said \"Hello\" -- she replied 'Hi'...", pipeline);

Options Copy Section

using Markdig.Extensions.SmartyPants;
var options = new SmartyPantOptions();
// Configure options as needed
var pipeline = new MarkdownPipelineBuilder()
    .UseSmartyPants(options)
    .Build();

---

Site/Docs/Extensions/Emphasis Extras Copy Section

---
title: Emphasis extras
---

Emphasis extras

Enable with .UseEmphasisExtras() (included in UseAdvancedExtensions()).

This extension adds several emphasis styles beyond standard bold and italic.

If you need improved emphasis parsing for Chinese/Japanese/Korean (CJK) text, see CJK friendly emphasis.

Strikethrough Copy Chapter

Wrap text with ~~ for strikethrough:

This is ~~deleted~~ text.

This is ~~deleted~~ text.

Subscript Copy Chapter

Wrap text with ~ for subscript:

H~2~O is water.

H~2~O is water.

Superscript Copy Chapter

Wrap text with ^ for superscript:

2^10^ is 1024.

2^10^ is 1024.

Inserted text Copy Chapter

Wrap text with ++ for inserted/underlined text:

This text has been ++inserted++.

This text has been ++inserted++.

Marked/highlighted text Copy Chapter

Wrap text with == for marked/highlighted text:

This is ==highlighted== text.

This is ==highlighted== text.

HTML output Copy Chapter

{.table}
| Syntax | HTML output |
|---|---|
| ~~text~~ | <del>text</del> |
| ~text~ | _text |
| ^text^ | ^text |
| ++text++ | <ins>text</ins> |
| ==text== | <mark>text</mark> |

Selective activation Copy Chapter

By default, all emphasis extras are enabled. Use EmphasisExtraOptions to enable only specific ones:

using Markdig.Extensions.EmphasisExtras;
var pipeline = new MarkdownPipelineBuilder()
    .UseEmphasisExtras(EmphasisExtraOptions.Strikethrough | EmphasisExtraOptions.Superscript)
    .Build();

Available options:

- EmphasisExtraOptions.Strikethrough
- EmphasisExtraOptions.Subscript
- EmphasisExtraOptions.Superscript
- EmphasisExtraOptions.Inserted
- EmphasisExtraOptions.Marked
- EmphasisExtraOptions.Default (all of the above)

---

Site/Docs/Extensions/Figures Footers Citations Copy Section

---
title: "Figures, footers & citations"
---

Figures, footers & citations

These three related extensions add HTML5 semantic elements to Markdown.

Figures Copy Chapter

Enable with .UseFigures() (included in UseAdvancedExtensions()).

Use ^^^ to create <figure> blocks with optional <figcaption>:

^^^
^^^ A beautiful mountain landscape

HTML output Copy Section

<figure>
  <p><img src="mountain.jpg" alt="A scenic mountain" /></p>
  <figcaption>A beautiful mountain landscape</figcaption>
</figure>

Multiple items in a figure Copy Section

^^^

^^^ A gallery of photos

Footers Copy Chapter

Enable with .UseFooters() (included in UseAdvancedExtensions()).

Use ^^ at the start of a line to create <footer> elements:

^^ This is a footer element.

HTML output Copy Section

<footer>This is a footer element.</footer>

Multi-line footers Copy Section

^^ This is the first line of the footer.
^^ This is the second line.

Citations Copy Chapter

Enable with .UseCitations() (included in UseAdvancedExtensions()).

Wrap text in double quotes "" to create a <cite> element:

""The Art of Computer Programming""

HTML output Copy Section

<p><cite>The Art of Computer Programming</cite></p>

In context Copy Section

As described in ""Design Patterns"" by the Gang of Four, the Observer pattern
is used to define a one-to-many dependency between objects.

Combining figures with citations Copy Chapter

^^^
"The best way to predict the future is to invent it." — Alan Kay

^^^ ""Computing in the 21st Century""

---

Site/Docs/Extensions/Footnotes Copy Section

---
title: Footnotes
---

Footnotes

Enable with .UseFootnotes() (included in UseAdvancedExtensions()).

Footnotes allow you to add references that appear at the bottom of the document, inspired by PHP Markdown Extra.

Syntax Copy Chapter

Define a footnote reference inline with [^label] and the footnote content elsewhere:

Here is a sentence with a footnote[^1].
And another with a named footnote[^note].
[^1]: This is the first footnote content.
[^note]: Footnotes can have any label, not just numbers.

Here is a sentence with a footnote[^1].

And another with a named footnote[^note].

[^1]: This is the first footnote content.
[^note]: Footnotes can have any label, not just numbers.

Multi-line footnotes Copy Chapter

Indent continuation lines to include multiple paragraphs in a footnote:

This has a long footnote[^long].
[^long]: This is the first paragraph of the footnote.
    This is the second paragraph. It must be indented to be
    included in the footnote.
    - Even lists work in footnotes
    - Like this one

This has a long footnote[^long].

[^long]: This is the first paragraph of the footnote.

This is the second paragraph. It must be indented to be
included in the footnote.

- Even lists work in footnotes
- Like this one

Inline footnotes Copy Chapter

You can also define footnotes inline (though this is less common):

This has an inline footnote^[This is the inline footnote content].

HTML output Copy Chapter

Footnote references become superscript links, and footnote definitions are collected into a <section> at the end of the page:

<p>Text with a footnote<a href="#fn:1" class="footnote-ref"><sup>1</sup></a>.</p>
<section class="footnotes">
  <ol>
    <li id="fn:1">
      <p>This is the footnote content.
        <a href="#fnref:1" class="footnote-back-ref">↩</a></p>
    </li>
  </ol>
</section>

Rules Copy Chapter

- Footnote labels are case-insensitive.
- Footnote definitions can appear anywhere in the document — they are always rendered at the end.
- Unused footnote definitions are not rendered.
- Multiple references to the same footnote share the same content.

---

Site/Docs/Extensions/Generic Attributes Copy Section

---
title: Generic attributes
---

Generic attributes

Enable with .UseGenericAttributes() (included in UseAdvancedExtensions()).

This extension allows attaching CSS classes, IDs, and arbitrary HTML attributes to nearly any Markdown element using {...} syntax. Inspired by PHP Markdown Extra — Special Attributes.

Syntax Copy Chapter

Place {...} after a Markdown element:

Heading {#custom-id .special-class}
A paragraph with attributes. {.lead}
A link{target="_blank" rel="noopener"}

Supported attribute types Copy Chapter

{.table}
| Syntax | Meaning | Example |
|---|---|---|
| #value | HTML id | {#my-id} |
| .value | CSS class | {.my-class} |
| key=value | HTML attribute | {data-count=5} |
| key="value" | Quoted attribute | {title="Hello World"} |

Multiple attributes can be combined:

A paragraph. {#intro .highlight data-section="overview"}

Applying to blocks Copy Chapter

Headings Copy Section

My Section {#section-1 .special}  Copy Chapter

Renders as: <h2 id="section-1" class="special">My Section</h2>

Paragraphs Copy Section

Place the attributes at the end of the paragraph:

This is a styled paragraph. {.lead .text-center}

Code blocks Copy Section

A styled blockquote {.fancy-quote}

The .table class is commonly used to apply Bootstrap-style table formatting:

{.table .table-striped}
| A | B |
|---|---|
| 1 | 2 |

Applying to inlines Copy Chapter

Links Copy Section

Click me{.btn .btn-primary}

Images Copy Section

{.rounded width="200"}

Emphasis Copy Section

Important text{.text-danger}

HTML output Copy Chapter

A paragraph. {.lead #intro}

Produces:

<p class="lead" id="intro">A paragraph.</p>

---

Site/Docs/Extensions/List Extras Copy Section

---
title: List extras
---

List extras

Enable with .UseListExtras() (included in UseAdvancedExtensions()).

This extension adds support for additional ordered list item types beyond the standard numeric 1. markers.

Alpha lists Copy Chapter

Use lowercase or uppercase letters followed by .:

a. First item
b. Second item
c. Third item

a. First item
b. Second item
c. Third item

Uppercase Copy Section

A. First item
B. Second item
C. Third item

A. First item
B. Second item
C. Third item

Roman numeral lists Copy Chapter

Use lowercase or uppercase Roman numerals followed by .:

i. First item
ii. Second item
iii. Third item
iv. Fourth item

i. First item
ii. Second item
iii. Third item
iv. Fourth item

Uppercase Roman Copy Section

I. First item
II. Second item
III. Third item

I. First item
II. Second item
III. Third item

HTML output Copy Chapter

The type attribute is set on the <ol> element:

<ol type="a">
  <li>First item</li>
  <li>Second item</li>
</ol>

{.table}
| Marker | HTML type |
|---|---|
| a. | a |
| A. | A |
| i. | i |
| I. | I |

---

Site/Docs/Extensions/Mathematics Copy Section

---
title: Mathematics
---

Mathematics

Enable with .UseMathematics() (included in UseAdvancedExtensions()).

This extension supports LaTeX-style math using $ for inline and $$ for display (block) math.

Inline math Copy Chapter

Wrap math expressions with single $:

The quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$.

The quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$.

Block math Copy Chapter

Wrap display equations with $$ on their own lines:

$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

HTML output Copy Chapter

- Inline math renders as <span class="math">\(...\)</span>
- Block math renders as <div class="math">\[...\]</div>

This HTML is designed to be consumed by math rendering libraries such as KaTeX or MathJax.

Example output Copy Section

<p>The formula is <span class="math">\(E = mc^2\)</span>.</p>

<div class="math">\[
\sum_{i=1}^n i = \frac{n(n+1)}{2}
\]</div>

Rules Copy Chapter

- Inline math ($...$) must not have a space immediately after the opening $ or before the closing $.
- Block math ($$...$$) uses $$ on separate lines.
- A single $ surrounded by spaces is treated as a literal dollar sign, not math.

Integrating with KaTeX or MathJax Copy Chapter

After rendering to HTML, include a math library in your page to render the formulas:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex/dist/katex.min.css">
<script src="https://cdn.jsdelivr.net/npm/katex/dist/katex.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/katex/dist/contrib/auto-render.min.js"></script>
<script>
    document.addEventListener("DOMContentLoaded", function() {
        renderMathInElement(document.body, {
          // customised options
          // • auto-render specific keys, e.g.:
          delimiters: [
              {left: '$$', right: '$$', display: true},
              {left: '$', right: '$', display: false},
              {left: '\\(', right: '\\)', display: false},
              {left: '\\[', right: '\\]', display: true}
          ],
          // • rendering keys, e.g.:
          throwOnError : false
        });
    });
</script>

Enable with .UseMediaLinks() (included in UseAdvancedExtensions()).

This extension converts image links () pointing to known media services into embedded players. When a Markdown image link targets a YouTube video, Vimeo clip, or other supported media URL, Markdig renders an <iframe> instead of an <img>.

Supported services Copy Chapter

{.table}
| Service | URL pattern |
|---|---|
| YouTube | youtube.com/watch?v=..., youtu.be/... |
| Vimeo | vimeo.com/... |
| Dailymotion | dailymotion.com/video/... |
| Yandex | video.yandex.ru/... |
| Odnoklassniki | ok.ru/video/... |

Syntax Copy Chapter

Use standard Markdown image syntax with a media URL:

HTML output Copy Chapter

<iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ"
        width="500" height="281"
        frameborder="0"
        allowfullscreen></iframe>

Direct media files Copy Chapter

For direct links to media files the extension supports:

{.table}
| Format | Type |
|---|---|
| .mp4, .webm, .ogg | <video> element |
| .mp3, .wav, .ogg | <audio> element |

Produces:

<video width="500" height="281" controls>
  <source type="video/mp4" src="video.mp4"></source>
</video>

Options Copy Chapter

using Markdig.Extensions.MediaLinks;
var options = new MediaOptions
{
    Width = "800",
    Height = "450",
    AddControlsProperty = true
};
var pipeline = new MarkdownPipelineBuilder()
    .UseMediaLinks(options)
    .Build();

---

Site/Docs/Extensions/Other Copy Section

---
title: Other extensions
---

Other extensions

This page covers smaller or more specialized extensions that are not part of UseAdvancedExtensions().

Bootstrap Copy Chapter

Enable with .UseBootstrap().

Adds Bootstrap CSS classes to generated HTML elements:

{.table}
| Element | Class applied |
|---|---|
| <table> | table |
| <blockquote> | blockquote |
| <figure> | figure |
| <figcaption> | figure-caption |
| <img> | img-fluid |

var pipeline = new MarkdownPipelineBuilder()
    .UseBootstrap()
    .Build();

Hardline breaks Copy Chapter

Enable with .UseSoftlineBreakAsHardlineBreak().

Makes every soft line break (a single newline inside a paragraph) render as a <br> tag instead of a space. Useful when you want each line to appear as written.

var pipeline = new MarkdownPipelineBuilder()
    .UseSoftlineBreakAsHardlineBreak()
    .Build();

Without this extension:

Line one
Line two

Renders as: <p>Line one Line two</p>

With this extension, it renders as: <p>Line one<br />Line two</p>

JIRA links Copy Chapter

Enable with .UseJiraLinks(options).

Automatically converts JIRA-style project references (e.g., PROJECT-123) into clickable links.

using Markdig.Extensions.JiraLinks;
var pipeline = new MarkdownPipelineBuilder()
    .UseJiraLinks(new JiraLinkOptions("https://jira.example.com/browse/"))
    .Build();
var html = Markdown.ToHtml("Fixed in PROJ-456.", pipeline);
// => <p>Fixed in <a href="https://jira.example.com/browse/PROJ-456">PROJ-456</a>.</p>

Globalization Copy Chapter

Enable with .UseGlobalization().

Adds appropriate dir attributes on HTML elements for right-to-left content. Detects the text direction of each block and annotates it.

var pipeline = new MarkdownPipelineBuilder()
    .UseGlobalization()
    .Build();

Referral links Copy Chapter

Enable with .UseReferralLinks(rels).

Adds rel attributes to all rendered links:

var pipeline = new MarkdownPipelineBuilder()
    .UseReferralLinks("nofollow", "noopener", "noreferrer")
    .Build();

All links will have rel="nofollow noopener noreferrer" added.

Self pipeline Copy Chapter

Enable with .UseSelfPipeline().

Detects the pipeline configuration from the Markdown document itself via a special HTML comment tag:

| A | B |
|---|---|
| 1 | 2 |

var pipeline = new MarkdownPipelineBuilder()
    .UseSelfPipeline() // Must be the only extension
    .Build();

Pragma lines Copy Chapter

Enable with .UsePragmaLines().

Inserts <span id="pragma-line-N"></span> markers into the HTML output for each source line. This is useful for editor synchronization (scrolling an editor to the rendered position).

var pipeline = new MarkdownPipelineBuilder()
    .UsePragmaLines()
    .Build();

Non-ASCII no escape Copy Chapter

Enable with .UseNonAsciiNoEscape().

Disables percent-encoding of non-ASCII characters in URLs. This works around a rendering bug in Internet Explorer/Edge with local file links containing non-US-ASCII characters.

var pipeline = new MarkdownPipelineBuilder()
    .UseNonAsciiNoEscape()
    .Build();

Precise source location Copy Chapter

Enable with .UsePreciseSourceLocation().

Maps every AST node to its exact position in the original source text via the Span property. Useful for syntax highlighting, editors, and linters.

var pipeline = new MarkdownPipelineBuilder()
    .UsePreciseSourceLocation()
    .Build();
var document = Markdown.Parse(text, pipeline);
foreach (var node in document.Descendants())
{
    Console.WriteLine($"{node.GetType().Name}: {node.Span}");
}

Disable HTML Copy Chapter

Use .DisableHtml() (a configuration option, not an extension).

Removes the HTML block parser and disables inline HTML parsing. This prevents raw HTML injection, but it is not a complete security solution on its own:

var pipeline = new MarkdownPipelineBuilder()
    .DisableHtml()
    .Build();

---

Site/Docs/Extensions/Readme Copy Section

---
title: Extensions
---

Extensions

Markdig ships with 20+ built-in extensions that go beyond CommonMark. Extensions are enabled via the MarkdownPipelineBuilder fluent API.

Quick start Copy Chapter

Enable all advanced extensions at once:

var pipeline = new MarkdownPipelineBuilder()
    .UseAdvancedExtensions()
    .Build();

Or enable specific extensions individually:

var pipeline = new MarkdownPipelineBuilder()
    .UsePipeTables()
    .UseFootnotes()
    .UseMathematics()
    .Build();

What UseAdvancedExtensions includes Copy Chapter

UseAdvancedExtensions() enables these extensions:

{.table}
| Extension | Method | Description |
|---|---|---|
| Alert blocks | .UseAlertBlocks() | GitHub-style [!NOTE], [!TIP], etc. |
| Abbreviations | .UseAbbreviations() | Abbreviation definitions: *[HTML]: Hyper Text Markup Language |
| Auto-identifiers | .UseAutoIdentifiers() | Automatic id attributes on headings |
| Citations | .UseCitations() | Citation text with ""..."" |
| Custom containers | .UseCustomContainers() | Fenced ::: div containers |
| Definition lists | .UseDefinitionLists() | <dl> / <dt> / <dd> lists |
| Emphasis extras | .UseEmphasisExtras() | Strikethrough, sub/superscript, inserted, marked |
| Figures | .UseFigures() | ^^^ figure blocks |
| Footers | .UseFooters() | ^^ footers |
| Footnotes | .UseFootnotes() | [^ref] footnotes |
| Grid tables | .UseGridTables() | Pandoc-style grid tables |
| Mathematics | .UseMathematics() | $...$ inline / $$...$$ block math |
| Media links | .UseMediaLinks() | Embed YouTube, Vimeo, etc. |
| Pipe tables | .UsePipeTables() | GitHub-style pipe tables |
| List extras | .UseListExtras() | Alpha and Roman numeral ordered lists |
| Task lists | .UseTaskLists() | - [x] / - [ ] checkboxes |
| Diagrams | .UseDiagrams() | Mermaid, nomnoml diagram blocks |
| Auto-links | .UseAutoLinks() | Auto-detect http://, www. URLs |
| Generic attributes | .UseGenericAttributes() | {.class #id key=value} attributes |

Additional extensions (not in UseAdvancedExtensions) Copy Chapter

{.table}
| Extension | Method | Description |
|---|---|---|
| Emoji | .UseEmojiAndSmiley() | :emoji: shortcodes and smileys |
| SmartyPants | .UseSmartyPants() | Smart quotes, dashes, ellipses |
| Bootstrap | .UseBootstrap() | Bootstrap CSS classes |
| Hardline breaks | .UseSoftlineBreakAsHardlineBreak() | Treat soft line breaks as <br> |
| YAML front matter | .UseYamlFrontMatter() | Parse and discard YAML front matter |
| JIRA links | .UseJiraLinks(options) | Auto-link Jira issue keys |
| Globalization | .UseGlobalization() | Right-to-left text support |
| Referral links | .UseReferralLinks(rels) | Add rel attributes to links |
| Self pipeline | .UseSelfPipeline() | Auto-configure pipeline from document |
| Pragma lines | .UsePragmaLines() | Line number pragma IDs |
| Non-ASCII no escape | .UseNonAsciiNoEscape() | Disable URI escaping for non-ASCII |
| CJK friendly emphasis | .UseCjkFriendlyEmphasis() | Improved emphasis delimiter rules for CJK text |

Extension ordering Copy Chapter

Extensions are applied in the order they are added to the builder. Most are order-independent, but UseGenericAttributes() should be added last because it modifies other parsers.

var pipeline = new MarkdownPipelineBuilder()
    .UsePipeTables()
    .UseFootnotes()
    .UseMathematics()
    .UseGenericAttributes() // Always last!
    .Build();

---

Site/Docs/Extensions/Tables Copy Section

---
title: Tables
---

Tables

Markdig supports two kinds of tables: pipe tables (GitHub-style) and grid tables (Pandoc-style).

Pipe tables Copy Chapter

Enable with .UsePipeTables() (included in UseAdvancedExtensions()).

Basic syntax Copy Section

Columns are separated by |. A header row is separated from the body by a line of dashes:

| Name     | Language | Stars |
|----------|----------|-------|
| Markdig  | C#       | 4.5k  |
| cmark    | C        | 1.6k  |
| markdown-it | JavaScript | 18k |

| Name | Language | Stars |
|----------|----------|-------|
| Markdig | C# | 4.5k |
| cmark | C | 1.6k |
| markdown-it | JavaScript | 18k |

Column alignment Copy Section

Use colons in the separator row to control alignment:

| Left   | Center  | Right  |
|:-------|:-------:|-------:|
| one    | two     | three  |
| four   | five    | six    |

| Left | Center | Right |
|:-------|:-------:|-------:|
| one | two | three |
| four | five | six |

Optional leading/trailing pipes Copy Section

The outer pipes are optional:

Name | Language
-----|--------
Markdig | C#
cmark | C

Name | Language
-----|--------
Markdig | C#
cmark | C

Inline formatting in cells Copy Section

Cells support inline Markdown — emphasis, code, links, etc.:

| Feature       | Status        |
|---------------|---------------|
| Bold      | ~~removed~~   |
| code        | link     |

| Feature | Status |
|---------------|---------------|
| Bold | ~~removed~~ |
| code | link |

Escaped pipes Copy Section

Use \| to include a literal pipe inside a cell:

| Expression   | Result |
|-------------|--------|
| a \| b    | a or b |

Options Copy Section

UsePipeTables accepts a PipeTableOptions object:

var pipeline = new MarkdownPipelineBuilder()
    .UsePipeTables(new PipeTableOptions
    {
        UseHeaderForColumnCount = true // GFM-compatible column counting
    })
    .Build();

| Option | Default | Description |
|----------------------------------|---------|-------------|
| RequireHeaderSeparator | true | Whether the dashed separator row is required. Set to false for Kramdown-style tables that allow headerless tables. |
| UseHeaderForColumnCount | false | When true, the header row's column count is authoritative — short rows are padded with empty cells and extra cells in wider rows are dropped. When false, the widest row determines the column count. |
| InferColumnWidthsFromSeparator | false | When true, populates TableColumnDefinition.Width based on the dash count of each column in the separator row, normalized to percentages that sum to 100. When false, Width stays 0 and no width information is emitted. |

#### Inferring column widths from the separator

With InferColumnWidthsFromSeparator = true, the width of each column is proportional to the number of - characters under it in the separator row. This is useful when you want authors to control relative column widths directly in the Markdown source.

var pipeline = new MarkdownPipelineBuilder()
    .UsePipeTables(new PipeTableOptions { InferColumnWidthsFromSeparator = true })
    .Build();

Given this input:

| A | B |
|---|--------|
| 1 | 2      |

the first column gets Width = 25 and the second Width = 75 (a 3:9 ratio of dashes, normalized to 100). The HTML renderer emits a <colgroup> with <col style="width:N%" /> entries so the widths flow through to the rendered table. The values are also available on Table.ColumnDefinitions[i].Width for custom renderers.

Grid tables Copy Chapter

Enable with .UseGridTables() (included in UseAdvancedExtensions()).

Grid tables use +, -, and | characters to draw a grid. They support multi-line cells, column spanning, and richer content than pipe tables.

Basic grid table Copy Section

+-----------+-----------+
| Header 1  | Header 2  |
+===========+===========+
| Cell 1    | Cell 2    |
+-----------+-----------+
| Cell 3    | Cell 4    |
+-----------+-----------+

+-----------+-----------+
| Header 1 | Header 2 |
+===========+===========+
| Cell 1 | Cell 2 |
+-----------+-----------+
| Cell 3 | Cell 4 |
+-----------+-----------+

Multi-line cells Copy Section

Grid table cells can contain multiple lines and block-level content:

+-----------+-------------------+
| Name      | Description       |
+===========+===================+
| Markdig   | A fast, powerful  |
|           | Markdown parser.  |
+-----------+-------------------+
| cmark     | The C reference   |
|           | implementation.   |
+-----------+-------------------+

+-----------+-------------------+
| Name | Description |
+===========+===================+
| Markdig | A fast, powerful |
| | Markdown parser. |
+-----------+-------------------+
| cmark | The C reference |
| | implementation. |
+-----------+-------------------+

Column spanning Copy Section

Use a continuous line (without + separators) to span columns:

+-------+-------+
| A     | B     |
+=======+=======+
| Cell spanning |
+-------+-------+

Use = instead of - for the header separator line (+===+===+).

---

Site/Docs/Extensions/Task Lists Copy Section

---
title: Task lists
---

Task lists

Enable with .UseTaskLists() (included in UseAdvancedExtensions()).

Task lists add checkbox-style list items, inspired by GitHub task lists.

Syntax Copy Chapter

Start a list item with [ ] (unchecked) or [x]/[X] (checked):

- [x] Write documentation
- [x] Implement feature
- [ ] Write tests
- [ ] Release

- [x] Write documentation
- [x] Implement feature
- [ ] Write tests
- [ ] Release

In ordered lists Copy Chapter

Task lists also work with ordered list items:

1. [x] First task
2. [ ] Second task
3. [ ] Third task

1. [x] First task
2. [ ] Second task
3. [ ] Third task

HTML output Copy Chapter

Checked items render as <input type="checkbox" disabled checked />, unchecked items as <input type="checkbox" disabled />:

<ul class="contains-task-list">
  <li class="task-list-item"><input type="checkbox" disabled checked /> Write docs</li>
  <li class="task-list-item"><input type="checkbox" disabled /> Write tests</li>
</ul>

---

Site/Docs/Extensions/Yaml Frontmatter Copy Section

---
title: YAML front matter
---

YAML front matter

Enable with .UseYamlFrontMatter() (not included in UseAdvancedExtensions()).

This extension parses YAML front matter blocks at the beginning of a document. The YAML content is parsed into the AST as a YamlFrontMatterBlock but is not rendered in the HTML output.

Syntax Copy Chapter

The YAML front matter is enclosed between --- delimiters at the very beginning of the document:

---
title: My Document
author: John Doe
date: 2025-01-15
tags:
  - markdown
  - documentation
---
My Document
Content starts here.

Usage Copy Chapter

using Markdig;
using Markdig.Extensions.Yaml;
using Markdig.Syntax;
var pipeline = new MarkdownPipelineBuilder()
    .UseYamlFrontMatter()
    .Build();
var document = Markdown.Parse(markdownText, pipeline);
// The YAML front matter is in the AST but not rendered
var html = document.ToHtml(pipeline); // Front matter is excluded
// Access the YAML block from the AST
var yamlBlock = document.Descendants<YamlFrontMatterBlock>().FirstOrDefault();
if (yamlBlock != null)
{
    // Get the raw YAML content (you can then parse it with a YAML library)
    var yaml = yamlBlock.Lines.ToString();
}

Rules Copy Chapter

- The --- opener must be the very first line of the document (no leading blank lines).
- The closing --- must appear on its own line.
- Only one YAML front matter block is recognized per document.

Processing the YAML content Copy Chapter

Markdig only parses the YAML front matter — it does not evaluate it. To process the YAML content, use a YAML library such as YamlDotNet:

using YamlDotNet.Serialization;
var yamlContent = yamlBlock.Lines.ToString();
var deserializer = new DeserializerBuilder().Build();
var metadata = deserializer.Deserialize<Dictionary<string, object>>(yamlContent);

Common use case Copy Chapter

YAML front matter is widely used in static site generators (Hugo, Jekyll, Lunet) to store document metadata like title, date, author, and tags. Markdig's YAML extension lets you preview such documents while stripping the metadata from the rendered output.

---

Site/Docs/Commonmark Copy Section

---
title: CommonMark syntax
---

CommonMark syntax

Markdig is fully compliant with the CommonMark specification (v0.31.2), passing 600+ spec tests. This page is a reference for all core Markdown syntax supported out of the box — no extensions required.

Headings Copy Chapter

ATX headings Copy Section

Use # characters (1–6) followed by a space: