A fast, powerful, CommonMark compliant, extensible Markdown processor for .NET
C# PowerShell
Latest commit d4bb7c0 Dec 19, 2016 @xoofx xoofx committed on GitHub Merge pull request #82 from christophano/bugfix/abbreviation_parser_fix
Fixes the IsValidAbbreviation method in AbbreviationParser
Permalink
Failed to load latest commit information.
img Update readme and benchmarks Jun 16, 2016
src Adds the test I ought to have included to begin with. Dec 19, 2016
.gitignore init Feb 9, 2016
license.txt init Feb 9, 2016
readme.md Update to latest CommonMark specs 0.27 Nov 19, 2016

readme.md

Markdig Build status NuGet Donate

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 can try Markdig online and compare it to other implementations on babelmark3

Features

  • 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.
  • Converter to HTML
  • Passing more than 600+ tests from the latest CommonMark specs (0.27)
  • Includes all the core elements of CommonMark:
    • including GFM fenced code blocks.
  • Extensible architecture
    • Even the core Markdown/CommonMark parsing is pluggable, so it allows to disable builtin Markdown/Commonmark parsing (e.g Disable HTML parsing) or change behaviour (e.g change matching # of a headers with @)
  • Built-in with 20+ extensions, including:
  • Compatible with .NET 3.5, 4.0+ and .NET Core (netstandard1.1+)

Documentation

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

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

Download

Markdig is available as a NuGet package: NuGet

Usage

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

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

var result = 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 HarLine and SmartyPants)

// Configure the pipeline with all advanced extensions active
var pipeline = new MarkdownPipelineBuilder().UseAdvancedExtensions().Build();
var result = Markdown.ToHtml("This is a text with some *emphasis*", pipeline);

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

Build

In order to build Markdig, you need to install .NET Core RTM

License

This software is released under the BSD-Clause 2 license.

Benchmarking

This is an early preview of the benchmarking against various implementations:

C implementations:

  • cmark (version: 0.25.0): Reference C implementation of CommonMark, no support for extensions
  • Moonshine (version: : popular C Markdown processor

.NET implementations:

JavaScript/V8 implementations:

Analysis of the results:

  • Markdig is roughly x100 times faster than MarkdownSharp, 30x times faster than docfx
  • Among the best in CPU, Extremely competitive and often faster than other implementations (not feature wise equivalent)
  • 15% to 30% less allocations and GC pressure

Because Marked.NET, MarkdownSharp and DocAsCode.MarkdownLite are way too slow, they are not included in the following charts:

BenchMark CPU Time

BenchMark Memory

Performance for x86:

BenchmarkDotNet-Dev=v0.9.7.0+
OS=Microsoft Windows NT 6.2.9200.0
Processor=Intel(R) Core(TM) i7-4770 CPU 3.40GHz, ProcessorCount=8
Frequency=3319351 ticks, Resolution=301.2637 ns, Timer=TSC
HostCLR=MS.NET 4.0.30319.42000, Arch=32-bit RELEASE
JitModules=clrjit-v4.6.1080.0

Type=Program  Mode=SingleRun  LaunchCount=2
WarmupCount=2  TargetCount=10

                     Method |      Median |    StdDev |Scaled |  Gen 0 | Gen 1|    Gen 2|Bytes Allocated/Op |
--------------------------- |------------ |---------- |------ | ------ |------|---------|------------------ |
                    Markdig |   5.5316 ms | 0.0372 ms |  0.71 |   56.00| 21.00|    49.00|      1,285,917.31 |
     CommonMark.NET(master) |   4.7035 ms | 0.0422 ms |  0.60 |  113.00|  7.00|    49.00|      1,502,404.60 |
CommonMark.NET(pipe_tables) |   5.6164 ms | 0.0298 ms |  0.72 |  111.00| 56.00|    49.00|      1,863,128.13 |
               MarkdownDeep |   7.8193 ms | 0.0334 ms |  1.00 |  120.00| 56.00|    49.00|      1,884,854.85 |
                      cmark |   4.2698 ms | 0.1526 ms |  0.55 |       -|     -|        -|                NA |
                  Moonshine |   6.0929 ms | 0.1053 ms |  1.28 |       -|     -|        -|                NA |
                  Strike.V8 |  10.5895 ms | 0.0492 ms |  1.35 |       -|     -|        -|                NA |
                 Marked.NET | 207.3169 ms | 5.2628 ms | 26.51 |    0.00|  0.00|     0.00|    303,125,228.65 |
              MarkdownSharp | 675.0185 ms | 2.8447 ms | 86.32 |   40.00| 27.00|    41.00|      2,413,394.17 |
Microsoft DocfxMarkdownLite | 166.3357 ms | 0.4529 ms | 21.27 |4,452.00|948.00|11,167.00|    180,218,359.60 |

Performance for x64:

BenchmarkDotNet-Dev=v0.9.6.0+
OS=Microsoft Windows NT 6.2.9200.0
Processor=Intel(R) Core(TM) i7-4770 CPU @ 3.40GHz, ProcessorCount=8
Frequency=3319351 ticks, Resolution=301.2637 ns, Timer=TSC
HostCLR=MS.NET 4.0.30319.42000, Arch=64-bit RELEASE [RyuJIT]
JitModules=clrjit-v4.6.1080.0

Type=Program  Mode=SingleRun  LaunchCount=2
WarmupCount=2  TargetCount=10

               Method |    Median |    StdDev |  Gen 0 |  Gen 1 | Gen 2 | Bytes Allocated/Op |
--------------------- |---------- |---------- |------- |------- |------ |------------------- |
          TestMarkdig | 5.5276 ms | 0.0402 ms | 109.00 |  96.00 | 84.00 |       1,537,027.66 |
    TestCommonMarkNet | 4.4661 ms | 0.1190 ms | 157.00 |  96.00 | 84.00 |       1,747,432.06 |
 TestCommonMarkNetNew | 5.3151 ms | 0.0815 ms | 229.00 | 168.00 | 84.00 |       2,323,922.97 |
     TestMarkdownDeep | 7.4076 ms | 0.0617 ms | 318.00 | 186.00 | 84.00 |       2,576,728.69 |

Donate

If you are using this library and find it useful for your project, please consider a donation for it!

Donate

Credits

Thanks to the fantastic work done by John 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 project BenchmarkDotNet that makes benchmarking so easy to setup!

Some decoding part (e.g HTML EntityHelper.cs) have been re-used from CommonMark.NET

Author

Alexandre MUTEL aka xoofx