Repository files navigation

Markdig is a fast, powerful,CommonMark compliant, extensible Markdown processor for .NET.

NOTE: The repository is under construction. There will be a dedicated website and proper documentation at some point!

You cantry Markdig online and compare it to other implementations onbabelmark3

• Very fast parser and html renderer (no-regexp), very lightweight in terms of GC pressure. See benchmarks
• Abstract Syntax Tree with precise source code location for syntax tree, useful when building a Markdown editor.
  • CheckoutMarkdown Editor v2 for Visual Studio 2022 powered by Markdig!
• Converter toHTML
• Passing more than600+ tests from the latestCommonMark specs (0.31.2)
• Includes all the core elements of CommonMark:
  • includingGFM fenced code blocks.
• Extensible architecture
  • Even the core Markdown/CommonMark parsing is pluggable, so it allows to disable builtin Markdown/Commonmark parsing (e.gDisable HTML parsing) or change behaviour (e.g change matching# of a headers with@)
• Roundtrip support: Parses trivia (whitespace, newlines and other characters) to support lossless parse ⭢ render roundtrip. This enables changing markdown documents without introducing undesired trivia changes.
• Built-in with20+ extensions, including:
  • 2 kind of tables:
    • Pipe tables (inspired from GitHub tables andPanDoc - Pipe Tables)
    • Grid tables (inspired fromPandoc - Grid Tables)
  • Extra emphasis (inspired fromPandoc - Emphasis andMarkdown-it)
    • strike through~~,
    • Subscript~
    • Superscript^
    • Inserted++
    • Marked==
  • Special attributes or attached HTML attributes (inspired fromPHP Markdown Extra - Special Attributes)
  • Definition lists (inspired fromPHP Markdown Extra - Definitions Lists)
  • Footnotes (inspired fromPHP Markdown Extra - Footnotes)
  • Auto-identifiers for headings (similar toPandoc - Auto Identifiers)
  • Auto-links generates links if a text starts withhttp:// orhttps:// orftp:// ormailto: orwww.xxx.yyy
  • Task Lists inspired fromGithub Task lists.
  • Extra bullet lists, supporting alpha bulleta.b. and roman bullet (i,ii...etc.)
  • Media support for media url (youtube, vimeo, mp4...etc.) (inspired from thisCommonMark discussion)
  • Abbreviations (inspired fromPHP Markdown Extra - Abbreviations)
  • Citation text by enclosing""..."" (inspired by thisCommonMark discussion)
  • Custom containers similar to fenced code block::: for generating a proper<div>...</div> instead (inspired by thisCommonMark discussion)
  • Figures (inspired from thisCommonMark discussion)
  • Footers (inspired from thisCommonMark discussion)
  • Mathematics/Latex extension by enclosing$$ for block and$ for inline math (inspired from thisCommonMark discussion)
  • Soft lines as hard lines
  • Emoji support (inspired fromMarkdown-it)
  • SmartyPants (inspired fromDaring Fireball - SmartyPants)
  • Bootstrap class (to output bootstrap class)
  • Diagrams extension whenever a fenced code block contains a special keyword, it will be converted to a div block with the content as-is (currently, supportsmermaid andnomnoml diagrams)
  • YAML Front Matter to parse without evaluating the front matter and to discard it from the HTML output (typically used for previewing without the front matter in MarkdownEditor)
  • JIRA links to automatically generate links for JIRA project references (Thanks to @clarkd:https://github.com/clarkd/MarkdigJiraLinker)
• Starting with Markdig version0.20.0+, Markdig is compatible only withNETStandard 2.0,NETStandard 2.1,NETCoreApp 2.1 andNETCoreApp 3.1.

If you are looking for support for an old .NET Framework 3.5 or 4.0, you can download Markdig0.18.3.

• WPF/XAML Markdown Renderer:markdig.wpf
• WPF/XAML Markdown Renderer:Neo.Markdig.Xaml
• Syntax highlighting:Markdig.SyntaxHighlighting
• Syntax highlighting using ColorCode-Universal:Markdown.ColorCode
• Syntax highlighting using Prism.js:WebStoating.Markdig.Prism
• Embedded C# scripting:Markdig.Extensions.ScriptCs

The repository is under construction. There will be a dedicated website and proper documentation at some point!

While there is not yet a dedicated documentation, you can find from thespecs documentation how to use these extensions.

In the meantime, you can have a "behind the scene" article about Markdig in my blog post"Implementing a Markdown Engine for .NET"

Markdig is available as a NuGet package:

AlsoMarkdig.Signed NuGet package provides signed assemblies.

The main entry point for the API is theMarkdig.Markdown class:

By default, without any options, Markdig is using the plain CommonMark parser:

varresult=Markdown.ToHtml("This is a text with some *emphasis*");Console.WriteLine(result);// prints: <p>This is a text with some <em>emphasis</em></p>

In order to activate most of all advanced extensions (except Emoji, SoftLine as HardLine, Bootstrap, YAML Front Matter, JiraLinks and SmartyPants)

// Configure the pipeline with all advanced extensions activevarpipeline=newMarkdownPipelineBuilder().UseAdvancedExtensions().Build();varresult=Markdown.ToHtml("This is a text with some *emphasis*",pipeline);

Try it online!

You can have a look at theMarkdownExtensions that describes all actionable extensions (by modifying the MarkdownPipeline)

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. For detailed contributing guidelines, please seecontributing.md.

In order to build Markdig, you need to install.NET 6.0

This software is released under theBSD-Clause 2 license.

The latest benchmark was collected on April 23 2022, against the following implementations:

• Markdig (version: 0.30.2): itself
• cmark (version: 0.30.2): Reference C implementation of CommonMark, no support for extensions
• CommonMark.NET(master) (version: 0.15.1): CommonMark implementation for .NET, no support for extensions, port of cmark, deprecated.
• MarkdownSharp (version: 2.0.5): Open source C# implementation of Markdown processor, as featured previously on Stack Overflow, regexp based.

// * Summary *BenchmarkDotNet=v0.13.1, OS=Windows 10.0.22000AMD Ryzen 9 5950X, 1 CPU, 32 logical and 16 physical cores.NET SDK=6.0.202  [Host]     : .NET 6.0.4 (6.0.422.16404), X64 RyuJIT  DefaultJob : .NET 6.0.4 (6.0.422.16404), X64 RyuJIT|            Method |       Mean |     Error |    StdDev ||------------------ |-----------:|----------:|----------:||           markdig |   1.979 ms | 0.0221 ms | 0.0185 ms ||             cmark |   2.571 ms | 0.0081 ms | 0.0076 ms ||    CommonMark.NET |   2.016 ms | 0.0169 ms | 0.0158 ms ||     MarkdownSharp | 221.455 ms | 1.4442 ms | 1.3509 ms |

• Markdig is roughlyx100 times faster than MarkdownSharp
• 20% faster than the reference cmark C implementation

Supports this project with a monthly donation and help me continue improving it. [Become a sponsor]

Lilith River, author ofImageflow Server, an easy on-demandimage editing, optimization, and delivery server

Thanks to the fantastic work done byJohn Mac Farlane for the CommonMark specs and all the people involved in making Markdown a better standard!

This project would not have been possible without this huge foundation.

Thanks also to the projectBenchmarkDotNet that makes benchmarking so easy to setup!

Some decoding part (e.g HTMLEntityHelper.cs) have been re-used fromCommonMark.NET

Thanks to the work done by @clarkd on theJIRA Link extension, now included with this project!

Alexandre MUTEL akaxoofx