4
[![Build Status]](https://travis-ci.org/github/cmark)
5
[![Windows Build Status]](https://ci.appveyor.com/project/github/cmark)
7
`cmark-gfm` is an extended version of the C reference implementation of
8
[CommonMark], a rationalized version of Markdown syntax with a spec. This
9
repository adds GitHub Flavored Markdown extensions to
10
[the upstream implementation], as defined in [the spec].
12
The rest of the README is preserved as-is from the upstream source. Note that
13
the library and binaries produced by this fork are suffixed with `-gfm` in
14
order to distinguish them from the upstream.
18
It provides a shared library (`libcmark`) with functions for parsing
19
CommonMark documents to an abstract syntax tree (AST), manipulating
20
the AST, and rendering the document to HTML, groff man, LaTeX,
21
CommonMark, or an XML representation of the AST. It also provides a
22
command-line program (`cmark`) for parsing and rendering CommonMark
25
Advantages of this library:
27
- **Portable.** The library and program are written in standard
28
C99 and have no external dependencies. They have been tested with
29
MSVC, gcc, tcc, and clang.
31
- **Fast.** cmark can render a Markdown version of *War and Peace* in
32
the blink of an eye (127 milliseconds on a ten year old laptop,
33
vs. 100-400 milliseconds for an eye blink). In our [benchmarks],
34
cmark is 10,000 times faster than the original `Markdown.pl`, and
35
on par with the very fastest available Markdown processors.
37
- **Accurate.** The library passes all CommonMark conformance tests.
39
- **Standardized.** The library can be expected to parse CommonMark
40
the same way as any other conforming parser. So, for example,
41
you can use `commonmark.js` on the client to preview content that
42
will be rendered on the server using `cmark`.
44
- **Robust.** The library has been extensively fuzz-tested using
45
[american fuzzy lop]. The test suite includes pathological cases
46
that bring many other Markdown parsers to a crawl (for example,
47
thousands-deep nested bracketed text or block quotes).
49
- **Flexible.** CommonMark input is parsed to an AST which can be
50
manipulated programmatically prior to rendering.
52
- **Multiple renderers.** Output in HTML, groff man, LaTeX, CommonMark,
53
and a custom XML format is supported. And it is easy to write new
54
renderers to support other formats.
56
- **Free.** BSD2-licensed.
58
It is easy to use `libcmark` in python, lua, ruby, and other dynamic
59
languages: see the `wrappers/` subdirectory for some simple examples.
61
There are also libraries that wrap `libcmark` for
62
[Go](https://github.com/rhinoman/go-commonmark),
63
[Haskell](https://hackage.haskell.org/package/cmark),
64
[Ruby](https://github.com/gjtorikian/commonmarker),
65
[Lua](https://github.com/jgm/cmark-lua),
66
[Perl](https://metacpan.org/release/CommonMark),
67
[Python](https://pypi.python.org/pypi/paka.cmark),
68
[R](https://cran.r-project.org/package=commonmark),
69
[Scala](https://github.com/sparsetech/cmark-scala) and
70
[Node.js](https://github.com/killa123/node-cmark).
75
Building the C program (`cmark`) and shared library (`libcmark`)
76
requires [cmake]. If you modify `scanners.re`, then you will also
77
need [re2c] \(>= 0.14.2\), which is used to generate `scanners.c` from
78
`scanners.re`. We have included a pre-generated `scanners.c` in
79
the repository to reduce build dependencies.
81
If you have GNU make, you can simply `make`, `make test`, and `make
82
install`. This calls [cmake] to create a `Makefile` in the `build`
83
directory, then uses that `Makefile` to create the executable and
84
library. The binaries can be found in `build/src`. The default
85
installation prefix is `/usr/local`. To change the installation
86
prefix, pass the `INSTALL_PREFIX` variable if you run `make` for the
87
first time: `make INSTALL_PREFIX=path`.
89
For a more portable method, you can use [cmake] manually. [cmake] knows
90
how to create build environments for many build systems. For example,
95
cmake .. # optionally: -DCMAKE_INSTALL_PREFIX=path
96
make # executable will be created as build/src/cmark
100
Or, to create Xcode project files on OSX:
107
The GNU Makefile also provides a few other targets for developers.
112
For more detailed benchmarks:
116
To run a test for memory leaks using `valgrind`:
120
To reformat source code using `clang-format`:
124
To run a "fuzz test" against ten long randomly generated inputs:
128
To do a more systematic fuzz test with [american fuzzy lop]:
130
AFL_PATH=/path/to/afl_directory make afl
132
Fuzzing with [libFuzzer] is also supported but, because libFuzzer is still
133
under active development, may not work with your system-installed version of
134
clang. Assuming LLVM has been built in `$HOME/src/llvm/build` the fuzzer can be
137
CC="$HOME/src/llvm/build/bin/clang" LIB_FUZZER_PATH="$HOME/src/llvm/lib/Fuzzer/libFuzzer.a" make libFuzzer
139
To make a release tarball and zip archive:
146
To compile with MSVC and NMAKE:
150
You can cross-compile a Windows binary and dll on linux if you have the
155
The binaries will be in `build-mingw/windows/bin`.
160
Instructions for the use of the command line program and library can
161
be found in the man pages in the `man` subdirectory.
166
By default, the library will pass through raw HTML and potentially
167
dangerous links (`javascript:`, `vbscript:`, `data:`, `file:`).
169
It is recommended that users either disable this potentially unsafe
170
feature by using the option `CMARK_OPT_SAFE` (or `--safe` with the
171
command-line program), or run the output through an HTML sanitizer
173
[XSS attacks](http://en.wikipedia.org/wiki/Cross-site_scripting).
178
There is a [forum for discussing
179
CommonMark](http://talk.commonmark.org); you should use it instead of
180
github issues for questions and possibly open-ended discussions.
181
Use the [github issue tracker](http://github.com/commonmark/CommonMark/issues)
182
only for simple, clear, actionable issues.
187
John MacFarlane wrote the original library and program.
188
The block parsing algorithm was worked out together with David
189
Greenspan. Vicent Marti optimized the C implementation for
190
performance, increasing its speed tenfold. Kārlis Gaņģis helped
191
work out a better parsing algorithm for links and emphasis,
192
eliminating several worst-case performance issues.
193
Nick Wellnhofer contributed many improvements, including
194
most of the C library's API and its test harness.
196
[benchmarks]: benchmarks.md
197
[the spec]: https://github.github.com/gfm/
198
[the upstream implementation]: https://github.com/jgm/cmark
199
[CommonMark]: http://commonmark.org
200
[cmake]: http://www.cmake.org/download/
201
[re2c]: http://re2c.org
202
[commonmark.js]: https://github.com/commonmark/commonmark.js
203
[Build Status]: https://img.shields.io/travis/github/cmark/master.svg?style=flat
204
[Windows Build Status]: https://ci.appveyor.com/api/projects/status/wv7ifhqhv5itm3d5?svg=true
205
[american fuzzy lop]: http://lcamtuf.coredump.cx/afl/
206
[libFuzzer]: http://llvm.org/docs/LibFuzzer.html
added
removed
deps/cmark/README.md
