|author||John MacFarlane <firstname.lastname@example.org>||Fri Dec 04 08:00:25 2015 -0800|
|committer||John MacFarlane <email@example.com>||Fri Dec 04 08:00:25 2015 -0800|
Install static library. Closes jgm/CommonMark#381.
It provides a shared library (
libcmark) with functions for parsing CommonMark documents to an abstract syntax tree (AST), manipulating the AST, and rendering the document to HTML, groff man, LaTeX, CommonMark, or an XML representation of the AST. It also provides a command-line program (
cmark) for parsing and rendering CommonMark documents.
Advantages of this library:
Portable. The library and program are written in standard C99 and have no external dependencies. They have been tested with MSVC, gcc, tcc, and clang.
Fast. cmark can render a Markdown version of War and Peace in the blink of an eye (127 milliseconds on a ten year old laptop, vs. 100-400 milliseconds for an eye blink). In our benchmarks, cmark is 10,000 times faster than the original
Markdown.pl, and on par with the very fastest available Markdown processors.
Accurate. The library passes all CommonMark conformance tests.
Standardized. The library can be expected to parse CommonMark the same way as any other conforming parser. So, for example, you can use
commonmark.js on the client to preview content that will be rendered on the server using
Robust. The library has been extensively fuzz-tested using american fuzzy lop. The test suite includes pathological cases that bring many other Markdown parsers to a crawl (for example, thousands-deep nested bracketed text or block quotes).
Flexible. CommonMark input is parsed to an AST which can be manipulated programatically prior to rendering.
Multiple renderers. Output in HTML, groff man, LaTeX, CommonMark, and a custom XML format is supported. And it is easy to write new renderers to support other formats.
It is easy to use
libcmark in python, lua, ruby, and other dynamic languages: see the
wrappers/ subdirectory for some simple examples.
Building the C program (
cmark) and shared library (
libcmark) requires cmake. If you modify
scanners.re, then you will also need re2c, which is used to generate
scanners.re. We have included a pre-generated
scanners.c in the repository to reduce build dependencies.
If you have GNU make, you can simply
make test, and
make install. This calls cmake to create a
Makefile in the
build directory, then uses that
Makefile to create the executable and library. The binaries can be found in
build/src. The default installation prefix is
/usr/local. To change the installation prefix, pass the
INSTALL_PREFIX variable if you run
make for the first time:
mkdir build cd build cmake .. # optionally: -DCMAKE_INSTALL_PREFIX=path make # executable will be created as build/src/cmark make test make install
Or, to create Xcode project files on OSX:
mkdir build cd build cmake -G Xcode .. open cmark.xcodeproj
The GNU Makefile also provides a few other targets for developers. To run a benchmark:
To run a test for memory leaks using
To reformat source code using
To run a “fuzz test” against ten long randomly generated inputs:
To do a more systematic fuzz test with american fuzzy lop:
AFL_PATH=/path/to/afl_directory make afl
To make a release tarball and zip archive:
To compile with MSVC and NMAKE:
You can cross-compile a Windows binary and dll on linux if you have the
The binaries will be in
Instructions for the use of the command line program and library can be found in the man pages in the
By default, the library will pass through raw HTML and potentially dangerous links (
It is recommended that users either disable this potentially unsafe feature by using the option
--safe with the command-line program), or run the output through an HTML sanitizer to protect against XSS attacks.
There is a forum for discussing CommonMark; you should use it instead of github issues for questions and possibly open-ended discussions. Use the github issue tracker only for simple, clear, actionable issues.
John MacFarlane wrote the original library and program. The block parsing algorithm was worked out together with David Greenspan. Vicent Marti optimized the C implementation for performance, increasing its speed tenfold. Kārlis Gaņģis helped work out a better parsing algorithm for links and emphasis, eliminating several worst-case performance issues. Nick Wellnhofer contributed many improvements, including most of the C library's API and its test harness.