DOCSEARCHbyAlgolia
Submit Docs

Markdig Documentation

repository·main·Indexed 26 days ago

https://github.com/xoofx/markdig

A high-performance, extensible Markdown processor for .NET that is fully CommonMark compliant. Markdig features a regex-free parser, low GC pressure, and a rich Abstract Syntax Tree (AST) supporting lossless roundtrips. It includes over 20 built-in extensions such as Tables, Task Lists, LaTeX Mathematics, Diagrams, and YAML Front Matter, configurable via the MarkdownPipelineBuilder. Compatible with .NET Standard 2.0/2.1 and .NET Core App 2.1/3.1.

Tokens
67.5K
Snippets
223
Records
393
Agent score
87%

What's inside Markdig

  1. Overview of Markdig features and extensions

    main

    Markdig is a fast, CommonMark-compliant Markdown processor for .NET. Key features include:

    • High Performance: Fast parser and HTML renderer with low GC pressure.
    • AST Support: Provides an Abstract Syntax Tree with precise source code locations.
    • Roundtrip Support: Supports lossless parse $\rightarrow$ render roundtrips by parsing trivia (whitespace, newlines).
    • Extensibility: Pluggable architecture allowing you to enable/disable specific parsing behaviors.

    Built-in Extensions

    Markdig includes over 20 extensions, including:

    • GitHub Style Alerts: [!Note], [!Tip], [!Important], [!Warning], [!Caution]
    • Tables: Pipe tables and Grid tables.
    • Extra Emphasis: Strike through ~~, Subscript ~, Superscript ^, Inserted ++, Marked ==.
    • Task Lists: GitHub-style task lists.
    • Mathematics: LaTeX support using $ and $$.
    • Diagrams: Supports mermaid and nomnoml via fenced code blocks.
    • Other: Footnotes, Auto-identifiers, Auto-links, Emoji, YAML Front Matter, and more.

  2. Overview of built-in inline parsers in Markdig

    main

    Markdig provides several built-in inline parser implementations that handle the parsing of specific Markdown syntax elements within a line of text. These parsers manage the identification and structure of:

    • Emphasis: Parsing of italic and bold text.
    • Links: Standard Markdown link syntax.
    • Autolinks: Automatic conversion of URLs and email addresses into links.
    • Code Span: Inline code blocks (e.g., code).
    • Escaping: Handling of backslash-escaped characters.

  3. Overview of Markdig features

    main

    Markdig provides several key capabilities for .NET developers:

    • Blazing fast: A regex-free parser and HTML renderer designed for minimal GC pressure.
    • CommonMark compliant: Passes 600+ tests from the CommonMark specification (0.31.2), including GFM fenced code blocks.
    • Extensible: Includes 20+ built-in extensions (Tables, task lists, math, diagrams, footnotes, emoji, etc.) and a pluggable architecture for custom parsers and renderers.
    • Rich AST: Provides a full abstract syntax tree with precise source locations and a Descendants API for document analysis.
    • Roundtrip support: Supports lossless parse $\rightarrow$ render roundtrips using trivia tracking, allowing for programmatic Markdown modification without unwanted changes.

  6. Understand the Markdig Block-level AST model

    main
    Markdig provides a block-level Markdown Abstract Syntax Tree (AST) model. This model is used by parsers to represent the structure of a Markdown document and by renderers to transform that structure into other formats. The syntax primitives include documents, blocks, source spans, and various node utilities.

  8. Supported Markdig Extensions

    main

    Markdig supports a wide range of Markdown extensions for advanced formatting. These include:

    • Tables: Pipe tables and Grid tables.
    • Extra Emphasis: Strike through (~~), Subscript (~), Superscript (^), Inserted (++), and Marked (==).
    • Lists & Items: Task Lists and Extra bullet lists.
    • Links & Identifiers: Auto-links, Auto-identifiers, and JIRA links.
    • Structural Elements: Definition lists, Footnotes, Custom containers, Figures, Footers, and YAML frontmatter.
    • Media & Content: Media support, Abbreviations, Citations, Emoji, and Diagrams.
    • Formatting & Styling: Special attributes, Soft lines as hard lines, SmartyPants, Bootstrap, and CJK-friendly Emphasis.
    • Mathematics: LaTeX extension using $$ for block math and $ for inline math.

  10. Understand the Markdig processing pipeline

    main

    Markdig processes Markdown through three distinct stages to transform text into structured output:

    1. Block parsing: The BlockProcessor uses BlockParser objects to identify block-level elements (like paragraphs, headings, and lists) line-by-line to build the initial AST skeleton.
    2. Inline parsing: The InlineProcessor visits every LeafBlock in the AST, using InlineParser objects to identify inline elements (like emphasis, links, and code spans) within the block text.
    3. Rendering: A renderer (such as HtmlRenderer) traverses the complete AST and dispatches each node to a corresponding ObjectRenderer to produce the final output (e.g., HTML).