mirror of
https://github.com/xoofx/markdig.git
synced 2026-11-18 10:21:28 +00:00
* 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>
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();