2014-09-06 13:28:25 +04:00
|
|
|
CommonMark
|
2014-09-07 06:00:47 +04:00
|
|
|
==========
|
2014-07-22 09:29:16 +04:00
|
|
|
|
2014-10-26 02:37:01 +03:00
|
|
|
CommonMark is a rationalized version of Markdown syntax,
|
2015-01-25 22:28:55 +03:00
|
|
|
with a [spec][the spec] and BSD-licensed reference
|
2014-10-26 02:37:01 +03:00
|
|
|
implementations in C and JavaScript.
|
2014-08-14 09:28:18 +04:00
|
|
|
|
2015-02-04 21:33:02 +03:00
|
|
|
[Try it now!](http://try.commonmark.org/)
|
2014-11-12 07:53:33 +03:00
|
|
|
|
2015-01-25 08:28:29 +03:00
|
|
|
For more information, see <http://commonmark.org>.
|
2014-07-22 09:29:16 +04:00
|
|
|
|
2015-01-25 08:28:29 +03:00
|
|
|
This repository contains the C reference implementation.
|
2015-01-25 08:47:46 +03:00
|
|
|
It provides a shared library (`libcmark`) with functions for parsing
|
|
|
|
CommonMark documents to an abstract syntax tree (AST), manipulating
|
2015-03-22 03:36:02 +03:00
|
|
|
the AST, and rendering the document to HTML, groff man,
|
|
|
|
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 08:47:46 +03:00
|
|
|
|
|
|
|
The library and program are written in standard C99 and have
|
|
|
|
no library dependencies. The parser is very fast, on par with
|
|
|
|
[sundown]: see the [benchmarks].
|
|
|
|
|
|
|
|
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 08:33:22 +03:00
|
|
|
|
|
|
|
[sundown]: https://github.com/vmg/sundown
|
|
|
|
[benchmarks]: benchmarks.md
|
2015-01-25 22:28:32 +03:00
|
|
|
[the spec]: http://spec.commonmark.org
|
2015-01-25 08:33:22 +03:00
|
|
|
|
2015-01-25 08:28:29 +03:00
|
|
|
Installing
|
|
|
|
----------
|
2014-11-07 22:15:18 +03:00
|
|
|
|
2014-11-12 07:45:30 +03:00
|
|
|
Building the C program (`cmark`) and shared library (`libcmark`)
|
2014-12-02 07:38:17 +03:00
|
|
|
requires [cmake]. If you modify `scanners.re`, then you will also
|
|
|
|
need [re2c], 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.
|
2014-11-12 07:45:30 +03:00
|
|
|
|
2014-11-13 00:17:06 +03: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 18:24:16 +03: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 07:45:30 +03:00
|
|
|
|
2014-11-13 00:17:06 +03: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 22:15:18 +03:00
|
|
|
|
|
|
|
mkdir build
|
|
|
|
cd build
|
2014-11-13 00:17:06 +03:00
|
|
|
cmake .. # optionally: -DCMAKE_INSTALL_PREFIX=path
|
2015-01-07 09:23:31 +03:00
|
|
|
make # executable will be created as build/src/cmark
|
2014-11-13 00:17:06 +03:00
|
|
|
make test
|
2014-11-07 22:15:18 +03:00
|
|
|
make install
|
|
|
|
|
2014-11-13 00:17:06 +03:00
|
|
|
Or, to create Xcode project files on OSX:
|
2014-11-07 22:15:18 +03:00
|
|
|
|
2014-11-13 00:17:06 +03:00
|
|
|
mkdir build
|
|
|
|
cd build
|
|
|
|
cmake -G Xcode ..
|
2015-01-22 11:37:38 +03:00
|
|
|
open cmark.xcodeproj
|
2014-11-12 07:45:30 +03:00
|
|
|
|
2014-11-13 00:17:06 +03:00
|
|
|
The GNU Makefile also provides a few other targets for developers.
|
2015-01-13 08:09:17 +03:00
|
|
|
To run a benchmark:
|
|
|
|
|
|
|
|
make bench
|
|
|
|
|
2014-11-12 18:51:06 +03:00
|
|
|
To run a "fuzz test" against ten long randomly generated inputs:
|
|
|
|
|
|
|
|
make fuzztest
|
|
|
|
|
2015-01-13 08:09:17 +03:00
|
|
|
To run a test for memory leaks using `valgrind`:
|
2014-11-12 18:51:06 +03:00
|
|
|
|
|
|
|
make leakcheck
|
|
|
|
|
2015-01-13 08:09:17 +03:00
|
|
|
To reformat source code using `astyle`:
|
|
|
|
|
|
|
|
make astyle
|
|
|
|
|
2014-11-17 03:00:36 +03:00
|
|
|
To make a release tarball and zip archive:
|
2014-11-12 18:51:06 +03:00
|
|
|
|
2014-11-17 03:00:36 +03:00
|
|
|
make archive
|
2014-11-12 18:43:17 +03:00
|
|
|
|
2015-01-25 08:28:29 +03:00
|
|
|
Installing (Windows)
|
|
|
|
--------------------
|
2014-11-14 19:27:16 +03:00
|
|
|
|
2014-11-25 00:01:45 +03:00
|
|
|
To compile with MSVC and NMAKE:
|
|
|
|
|
|
|
|
nmake
|
|
|
|
|
2014-11-14 19:27:16 +03: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 08:28:29 +03:00
|
|
|
Usage
|
|
|
|
-----
|
|
|
|
|
|
|
|
Instructions for the use of the command line program and library can
|
|
|
|
be found in the man pages in the `man` subdirectory.
|
|
|
|
|
|
|
|
**A note on security:**
|
|
|
|
This library does not attempt to sanitize link attributes or
|
|
|
|
raw HTML. If you use it in applications that accept
|
|
|
|
untrusted user input, you must run the output through an HTML
|
|
|
|
sanitizer to protect against
|
|
|
|
[XSS attacks](http://en.wikipedia.org/wiki/Cross-site_scripting).
|
2014-10-26 23:27:38 +03: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.
|
2014-11-14 02:42:29 +03:00
|
|
|
Use the [github issue tracker](http://github.com/jgm/CommonMark/issues)
|
2014-10-26 23:27:38 +03:00
|
|
|
only for simple, clear, actionable issues.
|
|
|
|
|
2014-11-23 04:20:41 +03:00
|
|
|
Authors
|
|
|
|
-------
|
|
|
|
|
2015-01-25 08:28:29 +03: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-13 00:17:06 +03:00
|
|
|
|
2014-11-07 22:15:18 +03:00
|
|
|
[cmake]: http://www.cmake.org/download/
|
2014-11-12 07:48:09 +03:00
|
|
|
[re2c]: http://re2c.org
|