@hackage cmark0.1.0.1

Haskell bindings to libcmark, CommonMark parser and renderer

cmark-hs

This package provides Haskell bindings for libcmark, the reference parser for CommonMark. It includes sources for libcmark, and does not require prior installation of the C library.

cmark provides the following advantages over existing Markdown libraries for Haskell:

  • Speed: Conversion speed is on par with the sundown library: about 30 times faster than pandoc, 24 times faster than the Haskell markdown package, 8 times faster than cheapskate.

  • Memory footprint: Memory footprint is on par with sundown. On one sample, the library uses a fourth the memory that markdown uses, and less than a tenth the memory that pandoc uses.

  • Robustness: cmark can handle whatever is thrown at it, without the exponential blowups in parsing time one can sometimes get with other libraries. For example, the input produced by this command will tie markdown and pandoc in knots:

    python -c "print ((500 * '[') + 'hi' + (500 * ']') + '(url)')"
    

    cmark handles it easily, with no slowdown.

  • Accuracy: cmark passes the CommonMark spec's suite of over 500 conformance tests.

  • Standardization: Since there is a spec and a comprehensive suite of tests, we can have a high degree of confidence that any two CommonMark implementations will behave the same. Thus, for example, one could use this library for server-side rendering and commonmark.js for client-side previewing.

  • Ease of installation: cmark has minimal dependencies.

cmark does not provide Haskell versions of the whole libcmark API, which is built around mutable cmark_node objects. Instead, it provides two functions:

  • markdownToHtml uses libcmark's parser and renderer for a maximally efficient conversion of CommonMark to HTML (as a Text). ("Smart punctuation" and a few other options can be enabled.)

    Prelude CMark Data.Text> markdownToHtml [optSmart] (pack "dog's *breakfast*")
    "<p>dog\8217s <em>breakfast</em></p>\n"
    
  • parseDocument uses libcmark's parser to produce a Node tree that can be processed further using Haskell. One can transform the tree using generics, convert it to another kind of structure (such as a Pandoc object that can be rendered using pandoc's renderers) or render it using a custom rendering function.

    Prelude CMark Data.Text> parseDocument  [optSmart] (pack "dog's *breakfast*")
    Node (Just (PosInfo {startLine = 1, startColumn = 1, endLine = 1, endColumn = 17})) DOCUMENT [Node (Just (PosInfo {startLine = 1, startColumn = 1, endLine = 1, endColumn = 17})) PARAGRAPH [Node Nothing (TEXT "dog") [],Node Nothing (TEXT "\8217") [],Node Nothing (TEXT "s ") [],Node Nothing EMPH [Node Nothing (TEXT "breakfast") []]]]
    

A note on security: This library does not attempt to sanitize HTML output. We recommend using xss-sanitize to filter the output.

A note on stability: There is a good chance the API will change significantly after this early release.