|
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
|