Files
markdig/site/docs/extensions
Stefan Greve 58d9752a6e Add Table of Contents Extension (#975)
* Add table of contents extension (#71)

* Replace a paragraph that consists of [TOC] alone with a TableOfContentsBlock
  when it closes, so the marker wins over links labeled TOC
* Render a nav with role doc-toc around nested lists of plain-text entries,
  and nothing for a document without headings
* Leave the marker a paragraph under trivia tracking, because no roundtrip
  renderer could write a replacement block back losslessly

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

* Add links from table of contents entries to headings

* Link an entry to its heading whenever the heading has a non-empty ID, and
  leave other entries as plain text instead of enabling AutoIdentifiers
* Write the link with WriteEscapeUrl, so BaseUrl and LinkRewriter treat it
  like a Markdown link to the same fragment
* Ignore the footnote test until the footnote link renderer honors
  EnableHtmlForInline, which a separate pull request fixes first

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

* Add heading level range to table of contents options

* Add MinLevel and MaxLevel, so a document title or deep subsections can be
  left out of the table of contents, as requested in #71
* Reject a minimum below 1 or a maximum below the minimum, but set no upper
  bound, because HeadingBlockParser.MaxLeadingCount can raise heading levels

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

* Update doc for table of contents extension

* Add a docs page covering the marker rules, the nav markup and its doc-toc
  role, links, options, CSS recipes and a custom renderer
* List the extension in the readme, the extension overview and menu, the
  Configure token list and the specs readme, as relative file links did

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

* Update test for footnote references in table of contents entries

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 21:06:57 +01:00
..
2026-02-22 14:11:54 +01:00
2026-02-22 14:11:54 +01:00

title
title
Extensions

Extensions

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

Quick start

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

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)

{.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
Relative file links .UseRelativeFileLinks() Rewrite links to .md files into links to .html pages
Table of Contents .UseTableOfContents() Replace a [TOC] paragraph with a nested list of the headings

Extension ordering

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();