GitHub's fork of cmark, a CommonMark parsing and rendering library and program in C
C C++ Python CMake Racket Makefile Other
Clone or download
Pull request Compare This branch is even with github:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
api_test Merge remote-tracking branch 'upstream/master' Jan 7, 2018
bench Added 'make newbench'. Dec 6, 2016
data Update CaseFolding to latest (#168) Dec 3, 2016
debian Debian packaging (#97) Jun 20, 2018
extensions add plaintext render func for strikethru Aug 9, 2018
man Parse rest of info string as meta (#103) Aug 8, 2018
src Parse rest of info string as meta (#103) Aug 8, 2018
test Parse rest of info string as meta (#103) Aug 8, 2018
tools Install ninja-build Jun 30, 2017
wrappers Add example of a Python wrapper which uses libcmark-gfmextensions. (#102 Jul 19, 2018
.editorconfig Use clang-format, llvm style, for formatting. Jul 28, 2015
.gitignore More runs in benchmark; .gitignore update Jun 30, 2017
.travis.yml Add static-only build to Travis test matrix Nov 18, 2017
CMakeLists.txt 0.28.3.gfm.14 Aug 10, 2018
COPYING COPYING: Update file name and remove duplicate section Aug 21, 2016
FindAsan.cmake Added 'Asan' build type. Feb 19, 2015
Makefile Remove normalize as an option per #190 (#194) Jun 30, 2017
Makefile.nmake Build static on Windows again Jan 7, 2018
README.md Merge remote-tracking branch 'upstream/master' Jan 7, 2018
appveyor.yml Test with multiple MSVC versions under Appveyor Mar 12, 2016
benchmarks.md Updated benchmarks. Jul 14, 2015
changelog.txt 0.28.3.gfm.14 Aug 10, 2018
nmake.bat Add Makefile and wrapper for nmake Nov 16, 2014
suppressions Table extension from c068469 reworked Jun 30, 2017
toolchain-mingw32.cmake Strip extensions API down and separate from core Jun 30, 2017
why-cmark-and-not-x.md Documented another strange hoedown behavior. Dec 13, 2015

README.md

cmark-gfm

Build Status Windows Build Status

cmark-gfm is an extended version of the C reference implementation of CommonMark, a rationalized version of Markdown syntax with a spec. This repository adds GitHub Flavored Markdown extensions to the upstream implementation, as defined in the spec.

The rest of the README is preserved as-is from the upstream source. Note that the library and binaries produced by this fork are suffixed with -gfm in order to distinguish them from the upstream.


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

  • 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 programmatically 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.

  • Free. BSD2-licensed.

It is easy to use libcmark in python, lua, ruby, and other dynamic languages: see the wrappers/ subdirectory for some simple examples.

There are also libraries that wrap libcmark for Go, Haskell, Ruby, Lua, Perl, Python, R, Scala and Node.js.

Installing

Building the C program (cmark) and shared library (libcmark) requires cmake. If you modify scanners.re, then you will also need re2c (>= 0.14.2), which is used to generate scanners.c from 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, 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: make INSTALL_PREFIX=path.

For a more portable method, you can use cmake manually. cmake knows how to create build environments for many build systems. For example, on FreeBSD:

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:

make bench

For more detailed benchmarks:

make newbench

To run a test for memory leaks using valgrind:

make leakcheck

To reformat source code using clang-format:

make format

To run a "fuzz test" against ten long randomly generated inputs:

make fuzztest

To do a more systematic fuzz test with american fuzzy lop:

AFL_PATH=/path/to/afl_directory make afl

Fuzzing with libFuzzer is also supported but, because libFuzzer is still under active development, may not work with your system-installed version of clang. Assuming LLVM has been built in $HOME/src/llvm/build the fuzzer can be run with:

CC="$HOME/src/llvm/build/bin/clang" LIB_FUZZER_PATH="$HOME/src/llvm/lib/Fuzzer/libFuzzer.a" make libFuzzer

To make a release tarball and zip archive:

make archive

Installing (Windows)

To compile with MSVC and NMAKE:

nmake

You can cross-compile a Windows binary and dll on linux if you have the mingw32 compiler:

make mingw

The binaries will be in build-mingw/windows/bin.

Usage

Instructions for the use of the command line program and library can be found in the man pages in the man subdirectory.

Security

By default, the library will pass through raw HTML and potentially dangerous links (javascript:, vbscript:, data:, file:).

It is recommended that users either disable this potentially unsafe feature by using the option CMARK_OPT_SAFE (or --safe with the command-line program), or run the output through an HTML sanitizer to protect against XSS attacks.

Contributing

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.

Authors

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.