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

Rendering HTML with MarkDig To convert the Markdown into HTML, I used the superb MarkDig library. This not only makes it super easy to convert basic Markdown. Markdig 0.24.0 A fast, powerful, CommonMark compliant, extensible Markdown processor for.NET with 20+ builtin extensions (pipetables, footnotes, definition lists. Apr 15, 2021 MarkDig uses a configuration pipeline of support features that you can add on top of the base parser. The.UseAdvancedExtensions method adds a number of common extensions (like GitHub-Flavored Markdown, List Extensions, etc.), but you can also add each of the components you want and customize exactly how you want Markdown to be parsed.

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

Markdig

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.
    • Checkout MarkdownEditor for Visual Studio powered by Markdig!
  • Converter to HTML
  • Passing more than 600+ tests from the latest CommonMark specs (0.29)
  • 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:
    • 2 kind of tables:
      • Pipe tables (inspired from GitHub tables and PanDoc - Pipe Tables)
      • Grid tables (inspired from Pandoc - Grid Tables)
    • Extra emphasis (inspired from Pandoc - Emphasis and Markdown-it)
      • strike through ~~,
      • Subscript ~
      • Superscript ^
      • Inserted ++
      • Marked
    • Special attributes or attached HTML attributes (inspired from PHP Markdown Extra - Special Attributes)
    • Definition lists (inspired from PHP Markdown Extra - Definitions Lists)
    • Footnotes (inspired from PHP Markdown Extra - Footnotes)
    • Auto-identifiers for headings (similar to Pandoc - Auto Identifiers)
    • Auto-links generates links if a text starts with http:// or https:// or ftp:// or mailto: or www.xxx.yyy
    • Task Lists inspired from Github Task lists.
    • Extra bullet lists, supporting alpha bullet a.b. and roman bullet (i, ii...etc.)
    • Media support for media url (youtube, vimeo, mp4...etc.) (inspired from this CommonMark discussion)
    • Abbreviations (inspired from PHP Markdown Extra - Abbreviations)
    • Citation text by enclosing '...' (inspired by this CommonMark discussion )
    • Custom containers similar to fenced code block ::: for generating a proper <div>...</div> instead (inspired by this CommonMark discussion )
    • Figures (inspired from this CommonMark discussion)
    • Footers (inspired from this CommonMark discussion)
    • Mathematics/Latex extension by enclosing $$ for block and $ for inline math (inspired from this CommonMark discussion)
    • Emoji support (inspired from Markdown-it)
    • SmartyPants (inspired from Daring 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, supports mermaid and nomnoml 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 version 0.20.0+, Markdig is compatible only with NETStandard 2.0, NETStandard 2.1, NETCoreApp 2.1 and NETCoreApp 3.1.
Markdig

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

Third Party Extensions

Documentation

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 the specs 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'

Download

Markdig is available as a NuGet package:

Also Markdig.Signed NuGet package provides signed assemblies.

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:

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

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:

  • Markdig (version: 0.5.x): itself
  • CommonMark.NET(master) (version: 0.11.0): CommonMark implementation for .NET, no support for extensions, port of cmark
    • CommonMark.NET(pipe_tables): An evolution of CommonMark.NET, supports extensions, not released yet
  • MarkdownDeep (version: 1.5.0): another .NET implementation
  • MarkdownSharp (version: 1.13.0): Open source C# implementation of Markdown processor, as featured on Stack Overflow, regexp based.
  • Marked.NET (version: 1.0.5) port of original marked.js project
  • Microsoft.DocAsCode.MarkdownLite (version: 2.0.1) used by the docfx project

JavaScript/V8 implementations:

  • Strike.V8 (version: 1.5.0) marked.js running in Google V8 (not .NET based)

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:

Performance for x86:

Performance for x64:

Donate

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

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.

Mark Digital Corp

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

Thanks to the work done by @clarkd on the JIRA Link extension (https://github.com/clarkd/MarkdigJiraLinker), now included with this project!

Author

Markdig css

Alexandre MUTEL aka xoofx

There are the folks who write YAML, and then there are the folks required to parse it. Let me assure you that the former is more natural than the latter. YAML, which stands for YAML Ain’t Markup Language, is a tricky syntax which promotes itself as a human-friendly data serialization standard for all programming languages.

What makes YAML tricky? The first audience for YAML is humans, not computers. The syntax aims to support constructs that can be hell to program for, with my favorite example being values that can either be a single value or an array across documents. The ambiguity of the syntax has spurred on multiple “YAML sucks” factions all over the world.

While the syntax can cause headaches, I still like YAML. YAML serves its purpose well in simple scenarios. This blog contains all post metadata in a terse front matter block.

In this post, you’ll see how we can use YAML.NET and Markdig to parse a blog post’s front matter.

Getting Started

We’ll first need to install two packages: YAML.NET and Markdig.

We will use Markdig to parse our blog posts, although we could also parse our files based on the standard convention of --- separators and forgo Markdig altogether. For this post, we’ll use it to handle slight discrepancies that might creep in between files.

The Front Matter

Jekyll powers this blog, a blog engine written in Ruby. It has a flexible front matter format that can adapt to the needs of the author and the theme applied to the blog. This blog post’s front matter looks something like this.

We represent all the values as string values, including the tags (a particular quirk of a paging plugin).

The C# Code

The first step we need to take is to create a class that represents our blog’s front matter. Note that many blogs will have different keys, and could vary from this example.

Once we have our front matter, we can create an extension method for our the Markdig MarkdownDocument class. The class will be where we pull our YAML front matter from in the form of a YamlFrontMatterBlock.

We need to remove the --- separators from our YAML block, or else YAML.NET will throw an exception. Another critical element of our code is the inclusion of MarkDig’s YAML frontmatter extension.

Without the extension, we won’t see the YAML block in our parsed document.

Markdig Syntax Highlighting

Finally, we can call our extension method after reading our files from disk.

Markdig Code

Running our code, we see the results of our front matter parser.

See Full List On Nuget.org

I hope this helped! Enjoy!





⇐ ⇐ Shazam Mac Spotify
⇒ ⇒ Microsoft Office Specialist Excel