Blame README.md

Packit 1f51f5
cmark-gfm-hs
Packit 1f51f5
============
Packit 1f51f5
Packit 1f51f5
This package provides Haskell bindings for [libcmark-gfm], the reference
Packit 1f51f5
parser for [GitHub Flavored Markdown], a fully specified variant of Markdown.
Packit 1f51f5
It includes sources for [libcmark-gfm] and does not require prior
Packit 1f51f5
installation of the C library.
Packit 1f51f5
Packit 1f51f5
cmark provides the following advantages over existing Markdown
Packit 1f51f5
libraries for Haskell:
Packit 1f51f5
Packit 1f51f5
  - **Speed:** cmark can render a Markdown version of *War and Peace* in
Packit 1f51f5
    the blink of an eye.  Conversion speed is on par with the
Packit 1f51f5
    [sundown] library, though we were unable to benchmark precisely,
Packit 1f51f5
    because [sundown] raised a malloc error when compiled into our
Packit 1f51f5
    benchmark suite. Relative to other Haskell Markdown libraries:
Packit 1f51f5
    cmark was 82 times faster than [cheapskate], 59 times faster than
Packit 1f51f5
    [markdown], 105 times faster than [pandoc], and 3 times faster
Packit 1f51f5
    than [discount].
Packit 1f51f5
Packit 1f51f5
  - **Memory footprint:**  Memory footprint is on par with [sundown].
Packit 1f51f5
    On one sample, the library uses a fourth the memory that [markdown]
Packit 1f51f5
    uses, and less than a tenth the memory that [pandoc] uses.
Packit 1f51f5
Packit 1f51f5
  - **Robustness:**  cmark can handle whatever is thrown at it,
Packit 1f51f5
    without the exponential blowups in parsing time that sometimes afflict
Packit 1f51f5
    other libraries.  (The input `bench/full-sample.md`,
Packit 1f51f5
    for example, causes both [pandoc] and [markdown] to grind to a
Packit 1f51f5
    halt.)  [libcmark-gfm] has been extensively fuzz-tested.
Packit 1f51f5
Packit 1f51f5
  - **Accuracy:**  cmark passes the CommonMark spec's suite of over
Packit 1f51f5
    600 conformance tests.
Packit 1f51f5
Packit 1f51f5
  - **Standardization:**  Since there is a spec and a comprehensive suite
Packit 1f51f5
    of tests, we can have a high degree of confidence that any two
Packit 1f51f5
    CommonMark implementations will behave the same.  Thus, for
Packit 1f51f5
    example, one could use this library for server-side rendering
Packit 1f51f5
    and [commonmark.js] for client-side previewing.
Packit 1f51f5
Packit 1f51f5
  - **Multiple renderers.**  Output in HTML, groff man, LaTeX, CommonMark,
Packit 1f51f5
    and a custom XML format is supported. And it is easy to write new
Packit 1f51f5
    renderers to support other formats.
Packit 1f51f5
Packit 1f51f5
  - **Ease of installation:** cmark is portable and has minimal
Packit 1f51f5
    dependencies.
Packit 1f51f5
Packit 1f51f5
cmark does not provide Haskell versions of the whole [libcmark-gfm]
Packit 1f51f5
API, which is built around mutable `cmark_node` objects.  Instead, it
Packit 1f51f5
provides functions for converting CommonMark to HTML (and other
Packit 1f51f5
formats), and a function for converting CommonMark to a `Node`
Packit 1f51f5
tree that can be processed further using Haskell.
Packit 1f51f5
Packit 1f51f5
**A note on security:**  This library does not attempt to sanitize
Packit 1f51f5
HTML output.  We recommend using [xss-sanitize] to filter the output,
Packit 1f51f5
or enabling `optSafe` to filter out all raw HTML and potentially
Packit 1f51f5
dangerous URLs.
Packit 1f51f5
Packit 1f51f5
**A note on stability:**  There is a good chance the API will change
Packit 1f51f5
significantly after this early release.
Packit 1f51f5
Packit 1f51f5
[GitHub Flavored Markdown]: https://github.github.com/gfm/
Packit 1f51f5
[libcmark-gfm]: http://github.com/github/cmark
Packit 1f51f5
[benchmarks]: https://github.com/jgm/cmark/blob/master/benchmarks.md
Packit 1f51f5
[cheapskate]: https://hackage.haskell.org/package/cheapskate
Packit 1f51f5
[pandoc]: https://hackage.haskell.org/package/pandoc
Packit 1f51f5
[sundown]: https://hackage.haskell.org/package/sundown
Packit 1f51f5
[markdown]: https://hackage.haskell.org/package/markdown
Packit 1f51f5
[commonmark.js]: http://github.com/jgm/commonmark.js
Packit 1f51f5
[xss-sanitize]: https://hackage.haskell.org/package/xss-sanitize
Packit 1f51f5
[discount]: https://hackage.haskell.org/package/discount