2015-04-16 19:55:05 +00:00
|
|
|
cmark
|
|
|
|
=====
|
2014-07-22 05:29:16 +00:00
|
|
|
|
2020-05-13 05:57:45 +00:00
|
|
|
[![CI
|
|
|
|
tests](https://github.com/commonmark/cmark/workflows/CI%20tests/badge.svg)](https://github.com/commonmark/cmark/actions)
|
2015-05-06 21:07:33 +00:00
|
|
|
|
2015-04-16 19:55:05 +00:00
|
|
|
`cmark` is the C reference implementation of [CommonMark], a
|
|
|
|
rationalized version of Markdown syntax with a [spec][the spec].
|
|
|
|
(For the JavaScript reference implementation, see
|
|
|
|
[commonmark.js].)
|
2014-08-14 05:28:18 +00:00
|
|
|
|
2015-01-25 05:47:46 +00:00
|
|
|
It provides a shared library (`libcmark`) with functions for parsing
|
|
|
|
CommonMark documents to an abstract syntax tree (AST), manipulating
|
2015-07-04 05:12:49 +00:00
|
|
|
the AST, and rendering the document to HTML, groff man, LaTeX,
|
2015-03-22 00:36:02 +00:00
|
|
|
CommonMark, or an XML representation of the AST. It also provides a
|
|
|
|
command-line program (`cmark`) for parsing and rendering CommonMark
|
|
|
|
documents.
|
2015-01-25 05:47:46 +00:00
|
|
|
|
2015-04-16 19:55:05 +00:00
|
|
|
Advantages of this library:
|
|
|
|
|
|
|
|
- **Portable.** The library and program are written in standard
|
2015-06-17 16:13:50 +00:00
|
|
|
C99 and have no external dependencies. They have been tested with
|
2015-04-16 19:55:05 +00:00
|
|
|
MSVC, gcc, tcc, and clang.
|
|
|
|
|
2015-06-17 16:13:50 +00:00
|
|
|
- **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.
|
2015-04-16 19:55:05 +00:00
|
|
|
|
|
|
|
- **Accurate.** The library passes all CommonMark conformance tests.
|
|
|
|
|
2015-04-16 20:57:29 +00:00
|
|
|
- **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`.
|
|
|
|
|
2015-04-16 19:55:05 +00:00
|
|
|
- **Robust.** The library has been extensively fuzz-tested using
|
2015-06-17 16:20:30 +00:00
|
|
|
[american fuzzy lop]. The test suite includes pathological cases
|
2015-04-16 19:55:05 +00:00
|
|
|
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
|
2016-08-09 12:21:31 +00:00
|
|
|
manipulated programmatically prior to rendering.
|
2015-04-16 19:55:05 +00:00
|
|
|
|
2015-07-04 05:12:49 +00:00
|
|
|
- **Multiple renderers.** Output in HTML, groff man, LaTeX, CommonMark,
|
2015-04-16 19:55:05 +00:00
|
|
|
and a custom XML format is supported. And it is easy to write new
|
|
|
|
renderers to support other formats.
|
|
|
|
|
|
|
|
- **Free.** BSD2-licensed.
|
2015-01-25 05:47:46 +00:00
|
|
|
|
|
|
|
It is easy to use `libcmark` in python, lua, ruby, and other dynamic
|
|
|
|
languages: see the `wrappers/` subdirectory for some simple examples.
|
2015-01-25 05:33:22 +00:00
|
|
|
|
2015-05-06 21:49:37 +00:00
|
|
|
There are also libraries that wrap `libcmark` for
|
2017-05-16 15:22:47 +00:00
|
|
|
[Go](https://github.com/rhinoman/go-commonmark),
|
|
|
|
[Haskell](https://hackage.haskell.org/package/cmark),
|
|
|
|
[Ruby](https://github.com/gjtorikian/commonmarker),
|
|
|
|
[Lua](https://github.com/jgm/cmark-lua),
|
2017-05-15 17:30:05 +00:00
|
|
|
[Perl](https://metacpan.org/release/CommonMark),
|
2017-05-16 15:28:03 +00:00
|
|
|
[Python](https://pypi.python.org/pypi/paka.cmark),
|
2017-05-16 15:22:47 +00:00
|
|
|
[R](https://cran.r-project.org/package=commonmark) and
|
2017-05-15 17:30:05 +00:00
|
|
|
[Scala](https://github.com/sparsetech/cmark-scala).
|
2015-01-25 05:33:22 +00:00
|
|
|
|
2015-01-25 05:28:29 +00:00
|
|
|
Installing
|
|
|
|
----------
|
2014-11-07 19:15:18 +00:00
|
|
|
|
2014-11-12 04:45:30 +00:00
|
|
|
Building the C program (`cmark`) and shared library (`libcmark`)
|
2014-12-02 04:38:17 +00:00
|
|
|
requires [cmake]. If you modify `scanners.re`, then you will also
|
2016-07-13 16:34:41 +00:00
|
|
|
need [re2c] \(>= 0.14.2\), which is used to generate `scanners.c` from
|
2014-12-02 04:38:17 +00:00
|
|
|
`scanners.re`. We have included a pre-generated `scanners.c` in
|
|
|
|
the repository to reduce build dependencies.
|
2014-11-12 04:45:30 +00:00
|
|
|
|
2014-11-12 21:17:06 +00:00
|
|
|
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
|
2015-01-24 15:24:16 +00:00
|
|
|
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`.
|
2014-11-12 04:45:30 +00:00
|
|
|
|
2014-11-12 21:17:06 +00:00
|
|
|
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:
|
2014-11-07 19:15:18 +00:00
|
|
|
|
|
|
|
mkdir build
|
|
|
|
cd build
|
2014-11-12 21:17:06 +00:00
|
|
|
cmake .. # optionally: -DCMAKE_INSTALL_PREFIX=path
|
2015-01-07 06:23:31 +00:00
|
|
|
make # executable will be created as build/src/cmark
|
2014-11-12 21:17:06 +00:00
|
|
|
make test
|
2014-11-07 19:15:18 +00:00
|
|
|
make install
|
|
|
|
|
2014-11-12 21:17:06 +00:00
|
|
|
Or, to create Xcode project files on OSX:
|
2014-11-07 19:15:18 +00:00
|
|
|
|
2014-11-12 21:17:06 +00:00
|
|
|
mkdir build
|
|
|
|
cd build
|
|
|
|
cmake -G Xcode ..
|
2015-01-22 08:37:38 +00:00
|
|
|
open cmark.xcodeproj
|
2014-11-12 04:45:30 +00:00
|
|
|
|
2014-11-12 21:17:06 +00:00
|
|
|
The GNU Makefile also provides a few other targets for developers.
|
2015-01-13 05:09:17 +00:00
|
|
|
To run a benchmark:
|
|
|
|
|
|
|
|
make bench
|
|
|
|
|
2016-12-06 09:56:59 +00:00
|
|
|
For more detailed benchmarks:
|
|
|
|
|
|
|
|
make newbench
|
|
|
|
|
2015-01-13 05:09:17 +00:00
|
|
|
To run a test for memory leaks using `valgrind`:
|
2014-11-12 15:51:06 +00:00
|
|
|
|
|
|
|
make leakcheck
|
|
|
|
|
2017-08-03 11:52:47 +00:00
|
|
|
To reformat source code using `clang-format`:
|
2015-01-13 05:09:17 +00:00
|
|
|
|
2017-08-03 11:52:47 +00:00
|
|
|
make format
|
2015-01-13 05:09:17 +00:00
|
|
|
|
2015-06-17 16:20:30 +00:00
|
|
|
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
|
|
|
|
|
2017-06-26 19:05:30 +00:00
|
|
|
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
|
|
|
|
|
2014-11-17 00:00:36 +00:00
|
|
|
To make a release tarball and zip archive:
|
2014-11-12 15:51:06 +00:00
|
|
|
|
2014-11-17 00:00:36 +00:00
|
|
|
make archive
|
2014-11-12 15:43:17 +00:00
|
|
|
|
2015-01-25 05:28:29 +00:00
|
|
|
Installing (Windows)
|
|
|
|
--------------------
|
2014-11-14 16:27:16 +00:00
|
|
|
|
2014-11-24 21:01:45 +00:00
|
|
|
To compile with MSVC and NMAKE:
|
|
|
|
|
|
|
|
nmake
|
|
|
|
|
2014-11-14 16:27:16 +00:00
|
|
|
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`.
|
|
|
|
|
2015-01-25 05:28:29 +00:00
|
|
|
Usage
|
|
|
|
-----
|
|
|
|
|
|
|
|
Instructions for the use of the command line program and library can
|
|
|
|
be found in the man pages in the `man` subdirectory.
|
|
|
|
|
2015-07-13 16:21:35 +00:00
|
|
|
Security
|
|
|
|
--------
|
|
|
|
|
2019-03-18 05:43:38 +00:00
|
|
|
By default, the library will scrub raw HTML and potentially
|
2015-07-13 16:21:35 +00:00
|
|
|
dangerous links (`javascript:`, `vbscript:`, `data:`, `file:`).
|
|
|
|
|
2019-03-18 05:43:38 +00:00
|
|
|
To allow these, use the option `CMARK_OPT_UNSAFE` (or
|
|
|
|
`--unsafe`) with the command line program. If doing so, we
|
|
|
|
recommend you use a HTML sanitizer specific to your needs to
|
|
|
|
protect against [XSS
|
|
|
|
attacks](http://en.wikipedia.org/wiki/Cross-site_scripting).
|
2014-10-26 20:27:38 +00:00
|
|
|
|
|
|
|
Contributing
|
|
|
|
------------
|
|
|
|
|
|
|
|
There is a [forum for discussing
|
|
|
|
CommonMark](http://talk.commonmark.org); you should use it instead of
|
|
|
|
github issues for questions and possibly open-ended discussions.
|
2017-11-16 17:31:28 +00:00
|
|
|
Use the [github issue tracker](http://github.com/commonmark/CommonMark/issues)
|
2014-10-26 20:27:38 +00:00
|
|
|
only for simple, clear, actionable issues.
|
|
|
|
|
2014-11-23 01:20:41 +00:00
|
|
|
Authors
|
|
|
|
-------
|
|
|
|
|
2015-01-25 05:28:29 +00:00
|
|
|
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.
|
2014-11-12 21:17:06 +00:00
|
|
|
|
2015-04-16 19:55:05 +00:00
|
|
|
[benchmarks]: benchmarks.md
|
|
|
|
[the spec]: http://spec.commonmark.org
|
|
|
|
[CommonMark]: http://commonmark.org
|
2014-11-07 19:15:18 +00:00
|
|
|
[cmake]: http://www.cmake.org/download/
|
2014-11-12 04:48:09 +00:00
|
|
|
[re2c]: http://re2c.org
|
2017-11-16 17:31:28 +00:00
|
|
|
[commonmark.js]: https://github.com/commonmark/commonmark.js
|
2015-06-17 16:20:30 +00:00
|
|
|
[american fuzzy lop]: http://lcamtuf.coredump.cx/afl/
|
2017-06-26 19:05:30 +00:00
|
|
|
[libFuzzer]: http://llvm.org/docs/LibFuzzer.html
|