��

cmark-gfm 是 C 语言参考实现的一个扩展版本，该参考实现对应的是具有规范定义的 Markdown 语法版本——CommonMark。此仓库为 [上游实现] 增加了 GitHub Flavored Markdown 扩展，如 [规范] 中所定义。

README 的其余部分从上游源代码中保持不变。请注意，此分支生成的库和二进制文件以 -gfm 作为后缀，以区别于上游版本。

---

它提供了一个共享库（libcmark），其中包含用于将 CommonMark 文档解析为抽象语法树（AST）、操作 AST 以及将文档渲染为 HTML、groff man、LaTeX、CommonMark 或 AST 的 XML 表示形式的函数。此外，它还提供了一个命令行程序（cmark），用于解析和渲染 CommonMark 文档。

此库的优点包括：

• 可移植性。 库和程序使用标准 C99 编写，没有外部依赖。它们已经在 MSVC、gcc、tcc 和 clang 上进行了测试。

• 快速。 cmark 能在瞬间渲染出《战争与和平》的 Markdown 版本（在十年前的笔记本电脑上用时 127 毫秒，而眨眼之间大约是 100-400 毫秒）。在我们的 [基准测试] 中，cmark 比最初的 Markdown.pl 快 10,000 倍，并且与目前最快的 Markdown 处理器速度相当。

• 精确。 此库通过了所有 CommonMark 兼容性测试。

• 标准化。 可以预期此库解析 CommonMark 的方式会与任何其他兼容解析器相同。例如，您可以在客户端使用 commonmark.js 预览内容，然后服务器端使用 cmark 进行渲染。

• 健壮。 此库已经使用 american fuzzy lop 进行了广泛的模糊测试。测试套件包括许多会使其他 Markdown 解析器运行缓慢的病理案例（例如，成千上万层嵌套的括号文本或块引用）。

• 灵活。 CommonMark 输入被解析为 AST，可以在渲染之前以编程方式对其进行操作。

• 多种渲染器。 支持输出 HTML、groff man、LaTeX、CommonMark 和自定义 XML 格式，且编写支持其他格式的新渲染器非常容易。

• 免费。 采用 BSD2 授权。

在 python、lua、ruby 等动态语言中使用 libcmark 很简单：请参见 wrappers/ 子目录中的一些简单示例。

还有库包装了 libcmark 以供 Go、Haskell、Ruby、Lua、Perl、Python、R、Tcl、Scala 和 Node.js 使用。

安装

构建 C 程序（cmark）和共享库（libcmark）需要 cmake。如果您修改 scanners.re，那么您还需要 re2c（版本 >= 0.14.2），它用于从 scanners.re 生成 scanners.c。我们已经在仓库中包含了一个预生成的 scanners.c，以减少构建依赖。

如果您有 GNU make，可以直接运行 make、make test 和 make install。这将调用 cmake 在 build 目录中创建一个 Makefile，然后使用该 Makefile 创建可执行文件和库。二进制文件可以在 build/src 目录中找到。默认的安装前缀是 /usr/local。要更改安装前缀，如果您第一次运行 make，请传递 INSTALL_PREFIX 变量：make INSTALL_PREFIX=路径。

对于更便携的方法，您可以使用 cmake 手动操作。cmake 知道如何为许多构建系统创建构建环境。例如，在 FreeBSD 上：

mkdir build cd build cmake .. # 可选：-DCMAKE_INSTALL_PREFIX=路径 make # 可执行文件将创建为 build/src/cmark make test make install

或者，要在 OSX 上创建 Xcode 项目文件：

mkdir build cd build cmake -G Xcode .. open cmark.xcodeproj

GNU Makefile 还为开发者提供了几个其他目标。要运行基准测试：

make bench

要运行更详细的基准测试：

make newbench

要使用 valgrind 运行内存泄漏测试：

make leakcheck

要使用 clang-format 重新格式化源代码：

make format

要对十个长的随机生成的输入进行 "模糊测试"：

make fuzztest

要使用 american fuzzy lop 进行更系统的模糊测试：

AFL_PATH=/路径到/afl_directory make afl

也支持使用 libFuzzer 进行模糊测试，但由于 libFuzzer 仍在积极开发中，可能与您系统安装的 clang 版本不兼容。假设 LLVM 已经在 $HOME/src/llvm/build 中构建，模糊测试可以使用以下命令运行：

CC="$HOME/src/llvm/build/bin/clang"LI{B}_{F}UZZE{R}_{P}ATH="$HOME/src/llvm/lib/Fuzzer/libFuzzer.a" make libFuzzer

要制作发布 tarball 和 zip 存档：

make archive

安装（Windows）

要在 Windows 上使用 MSVC 和 NMAKE 进行编译：

nmake

如果您在 Linux 上有 mingw32 编译器，可以交叉编译 Windows 二进制文件和 dll：

make mingw

二进制文件将在 build-mingw/windows/bin 中。

使用

命令行程序和库的使用说明可以在 man 子目录中的手册页中找到。

安全

默认情况下，库会清除原始 HTML 和可能危险的链接（javascript:、vbscript:、data:、file:）。

要允许这些内容，请在命令行程序中使用选项 CMARK_OPT_UNSAFE（或 --unsafe）。如果这样做，我们建议您使用针对您的需求的具体 HTML 清理器来保护免受 XSS 攻击。

贡献

有一个 论坛讨论 CommonMark；对于问题和可能的开放讨论，您应该使用它而不是 github 问题。仅使用 github 问题跟踪器 来报告简单、明确、可操作的问题。

作者

John MacFarlane 编写了原始库和程序。 区块解析算法是由 John MacFarlane 和 David Greenspan 共同研究的。Vicent Marti 对 C 实现进行了性能优化，将其速度提高了十倍。Kārlis Gaņģis 帮助研究出一个更好的链接和强调解析算法，消除了几个最坏情况的性能问题。Nick Wellnhofer 贡献了许多改进，包括 C 库的大部分 API 和其测试工具。