cmark

https://github.com/commonmark/cmark
Admin
cmark is the C reference implementation of CommonMark, providing a shared library and command-line...
Tokens:92,692
Snippets:1,021
Trust Score:8.8
License:BSD-2-Clause
Update:3 days ago
Show doc for...
Tokens:
Raw
### Install targets and files

Source: https://github.com/commonmark/cmark/blob/master/src/CMakeLists.txt

Installs the cmark_exe and cmark targets to bin/lib directories, exports them as cmark-targets, installs libcmark.pc to pkgconfig, and installs public headers (cmark.h, cmark_export.h, cmark_version.h) to the include directory.

```cmake
install(TARGETS cmark_exe cmark
  EXPORT cmark-targets
  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
  LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
  ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
  )

install(FILES ${CMAKE_CURRENT_BINARY_DIR}/libcmark.pc
  DESTINATION ${CMAKE_INSTALL_LIBDIR}/pkgconfig)

install(FILES
  cmark.h
  ${CMAKE_CURRENT_BINARY_DIR}/cmark_export.h
  ${CMAKE_CURRENT_BINARY_DIR}/cmark_version.h
  DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
  )
```

--------------------------------

### Equivalent Markdown list example

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Equivalent Markdown version of the AsciiDoc example, showing list item continuation with indented blocks and nested lists. Presented to highlight Markdown's readability.

```markdown
1.  List item one.

    List item one continued with a second paragraph followed by an
    Indented block.

        $ ls *.sh
        $ mv *.sh ~/tmp

    List item continued with a third paragraph.

2.  List item two continued with an open block.

    This paragraph is part of the preceding list item.

    1. This list is nested and does not require explicit item continuation.

       This paragraph is part of the preceding list item.

    2. List item b.

    This paragraph belongs to item two of the outer list.
```

--------------------------------

### HTML output: two lists with intervening paragraph

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

HTML output for the preceding Markdown example, showing two separate lists with a paragraph between them.

```html
<ul>
<li>foo</li>
</ul>
<p>bar</p>
<ul>
<li>baz</li>
</ul>

```

--------------------------------

### Loose and tight list ambiguity

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Illustrates the ambiguity of when list items get wrapped in <p> tags and whether a list can be partially loose and partially tight.

```markdown
1. one

2. two
3. three
```

--------------------------------

### HTML output: single list item with continuation paragraph

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

HTML output for the preceding Markdown example, showing a single list item with two paragraphs.

```html
<ul>
<li>
<p>one</p>
<p>two</p>
</li>
</ul>

```

--------------------------------

### HTML output: single list with subparagraphs

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Alternative HTML output for the same Markdown example, showing a single list with subparagraphs and a nested list.

```html
<ul>
<li>
<p>foo</p>
<p>bar</p>
<ul>
<li>baz</li>
</ul>
</li>
</ul>

```

--------------------------------

### Both left and right-flanking delimiter runs

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Examples of delimiter runs that are both left and right-flanking.

```markdown
 abc***def
"abc"_"def"
```

--------------------------------

### HTML output: blockquote with list and continuation paragraph

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

HTML output for the preceding Markdown example, showing a blockquote containing a list item with two paragraphs.

```html
<blockquote>
<ul>
<li>
<p>one</p>
<p>two</p>
</li>
</ul>
</blockquote>

```

--------------------------------

### AsciiDoc list example from manual

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Sample AsciiDoc from the AsciiDoc manual illustrating list item continuation with an indented block and an open block. Used to compare readability with Markdown.

```asciidoc
1. List item one.
+
List item one continued with a second paragraph followed by an
Indented block.
+
.................
$ ls *.sh
$ mv *.sh ~/tmp
.................
+
List item continued with a third paragraph.

2. List item two continued with an open block.
+
--
This paragraph is part of the preceding list item.

a. This list is nested and does not require explicit item
continuation.
+
This paragraph is part of the preceding list item.

b. List item b.

This paragraph belongs to item two of the outer list.
--
```

--------------------------------

### Markdown example: blockquote with list and continuation paragraph

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Shows a blockquote containing a list item with a continuation paragraph, demonstrating the same behavior inside a blockquote.

```markdown
>   - one
>
>  two

```

--------------------------------

### Run spec tests with spec_tests.py

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Command to run the conformance tests against a Markdown program using the provided spec_tests.py script.

```bash
python test/spec_tests.py --spec spec.txt --program PROGRAM
```

--------------------------------

### Left-flanking but not right-flanking delimiter runs

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Examples of delimiter runs that are left-flanking but not right-flanking.

```markdown
***abc
  _abc
**"abc"
 _"abc"
```

--------------------------------

### Right-flanking but not left-flanking delimiter runs

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Examples of delimiter runs that are right-flanking but not left-flanking.

```markdown
 abc***
 abc_
"abc"**
"abc"_
```

--------------------------------

### Neither left nor right-flanking delimiter runs

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Examples of delimiter runs that are neither left nor right-flanking.

```markdown
abc *** def
a _ b
```

--------------------------------

### Markdown example: indented list with continuation paragraph

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Shows a list item with a continuation paragraph that is indented less than the list marker, which Markdown.pl parses as a single list item.

```markdown
   - one

  two

```

--------------------------------

### Info string with extra attributes

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

An info string can contain additional words after the language name; only the first word is used for the language class.

```markdown
~~~~    ruby startline=3 $%@#$
def foo(x)
  return 3
end
~~~~~~~

```

```html
<pre><code class="language-ruby">def foo(x)
  return 3
end
</code></pre>

```

--------------------------------

### Empty list item ambiguity

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Shows a list with an empty item to illustrate the ambiguity of whether list items can be empty.

```markdown
* a
*
* b
```

--------------------------------

### Markdown example: list item with indented code block

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Shows a common pattern where indented code is placed eight spaces after the list marker.

```markdown
1.  foo

        indented code

```

--------------------------------

### Opening and closing backtick strings must be equal in length

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

When opening and closing backtick strings differ in length, the shorter string is treated as literal text. The example shows input and its HTML output.

```markdown
`foo``bar``
```

```html
<p>`foo<code>bar</code></p>
```

--------------------------------

### Multiple link reference definitions ambiguity

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Shows two definitions for the same reference to illustrate the ambiguity of which definition takes precedence.

```markdown
[foo]: /url1
[foo]: /url2

[foo][]
```

--------------------------------

### Info string with language name

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

An info string can be provided after the opening fence; the first word is typically used to specify the language, and in HTML output it adds a class like 'language-ruby'.

```markdown
```ruby
def foo(x)
  return 3
end
```

```

```html
<pre><code class="language-ruby">def foo(x)
  return 3
end
</code></pre>

```

--------------------------------

### Markdown example: list item with subparagraph not indented as far

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Shows a list item where the second paragraph is not indented as far as the first, illustrating a proposed rule.

```markdown
 10. foo

   bar  

```

--------------------------------

### Emphasis precedence ambiguity

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Shows nested emphasis markers to illustrate the ambiguity of precedence rules for emphasis and strong emphasis.

```markdown
*foo *bar* baz*
```

--------------------------------

### Build and test with cmake on FreeBSD

Source: https://github.com/commonmark/cmark/blob/master/README.md

Manual cmake build steps for a portable build. The executable is created as build/src/cmark. Optionally set CMAKE_INSTALL_PREFIX to change the install location.

```shell
cmake -S . -B build  # optionally: -DCMAKE_INSTALL_PREFIX=path
cmake --build build  # executable will be created as build/src/cmark
ctest --test-dir build
cmake --install build
```

--------------------------------

### Markdown example: two lists with intervening paragraph

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Shows a Markdown list with a blank line and a nested list that, under the four-space rule, is parsed as two lists with an intervening paragraph.

```markdown
- foo

  bar

  - baz

```

--------------------------------

### Closing code fences cannot have info strings

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

A closing fence with an info string is not recognized as a closing fence; the line remains inside the code block.

```markdown
```
``` aaa
```

```

```html
<pre><code>``` aaa
</code></pre>

```

--------------------------------

### Inline precedence ambiguity

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Shows a link containing code spans to illustrate the ambiguity of precedence rules for inline structure markers.

```markdown
[a backtick (`)](/url) and [another backtick (`)](/url).
```

--------------------------------

### Nested list with blank lines ambiguity

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Shows a nested list with blank lines to illustrate the ambiguity of list item wrapping and tight/loose list behavior.

```markdown
1.  one
    - a

    - b
2.  two
```

--------------------------------

### List item with heading ambiguity

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Shows a list item containing a heading to illustrate the ambiguity of whether list items can include section headings.

```markdown
- # Heading
```

--------------------------------

### Info string with semicolon

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

An info string can contain a semicolon; the language class becomes 'language-;'.

```markdown
````;
````

```

```html
<pre><code class="language-;"></code></pre>

```

--------------------------------

### Generate and install CMake package config files

Source: https://github.com/commonmark/cmark/blob/master/src/CMakeLists.txt

Generates cmark-config.cmake and cmark-config-version.cmake using configure_package_config_file and write_basic_package_version_file with SameMajorVersion compatibility. Installs these files and the exported targets file with namespace cmark:: to the CMake package directory.

```cmake
# generate cmark-config.cmake and cmark-config-version.cmake files
configure_package_config_file(
  "cmarkConfig.cmake.in"
  "${CMAKE_CURRENT_BINARY_DIR}/generated/cmark-config.cmake"
  INSTALL_DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/cmark")
write_basic_package_version_file(
  "${CMAKE_CURRENT_BINARY_DIR}/generated/cmark-config-version.cmake"
  VERSION ${PROJECT_VERSION}
  COMPATIBILITY SameMajorVersion)
# install config and version file
install(
  FILES "${CMAKE_CURRENT_BINARY_DIR}/generated/cmark-config.cmake"
        "${CMAKE_CURRENT_BINARY_DIR}/generated/cmark-config-version.cmake"
  DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/cmark"
)
# install targets file
install(
  EXPORT "cmark-targets"
  NAMESPACE "cmark::"
  DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/cmark"
)
```

--------------------------------

### Indented code block ambiguity

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Shows a paragraph followed by an indented line to illustrate the ambiguity of whether a blank line is required before an indented code block.

```markdown
paragraph
    code?
```

--------------------------------

### Code fences cannot contain internal spaces or tabs

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

An opening fence with internal spaces is not recognized as a code fence; it is treated as inline code.

```markdown
``` ```
aaa

```

```html
<p><code> </code>
aaa</p>

```

--------------------------------

### Supported emphasis patterns with triple and double delimiters

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

These patterns are supported by Markdown.pl and most implementations for nested emphasis using triple and double delimiters.

```markdown
***strong emph***
***strong** in emph*
***emph* in strong**
**in strong *emph***
*in emph **strong***
```

--------------------------------

### Fenced code block with opening fence indented 3 spaces

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

A fenced code block where the opening fence is indented three spaces and the closing fence is indented two spaces. The indentation of the closing fence need not match the opening fence.

```markdown
   ```
aaa
  ```

```

```html
<pre><code>aaa
</code></pre>

```

--------------------------------

### Less widely supported emphasis patterns

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

These patterns are less widely supported but the intent is clear and they are useful, especially in contexts like bibliography entries.

```markdown
*emph *with emph* in it*
**strong **with strong** in it**
```

--------------------------------

### cmark_node_get_list_start

Source: https://github.com/commonmark/cmark/blob/master/man/man3/cmark.3

Returns starting number of the node, if it is an ordered list, otherwise 0.

```APIDOC
## cmark_node_get_list_start

### Description
Returns starting number of the node, if it is an ordered list, otherwise 0.

### Signature
`int cmark_node_get_list_start(cmark_node *node)`

### Parameters
- **node** (cmark_node*) - Required - The node to query.

### Returns
- **int** - Starting number if ordered list, otherwise 0.
```

--------------------------------

### Fenced code block with closing fence indented up to 3 spaces

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

A fenced code block where the closing fence is indented up to three spaces. The indentation of the closing fence need not match the opening fence.

```markdown
```
aaa
  ```

```

```html
<pre><code>aaa
</code></pre>

```

--------------------------------

### Block-level vs inline-level precedence ambiguity

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Shows a list item containing a code span with a hyphen to illustrate the ambiguity of precedence rules between block-level and inline-level structure.

```markdown
- `a long code span can contain a hyphen like this
  - and it can screw things up`
```

--------------------------------

### Unclosed backtick string with newline yields literal backtick

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

A backtick string that is not closed by a matching backtick string results in literal backticks. The example shows input and its HTML output.

```markdown
`foo
```

```html
<p>`foo</p>
```

--------------------------------

### Unclosed backtick string yields literal backticks

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

When a backtick string is not closed by a matching backtick string, the backticks are treated as literal text. The example shows input and its HTML output.

```markdown
```foo``
```

```html
<p>```foo``</p>
```

--------------------------------

### Run memory leak check with valgrind

Source: https://github.com/commonmark/cmark/blob/master/README.md

Runs a test for memory leaks using valgrind. Requires valgrind to be installed.

```shell
make leakcheck
```

--------------------------------

### Fenced code block interrupting a paragraph

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

A fenced code block can interrupt a paragraph and be followed directly by a paragraph without a blank line.

```markdown
foo
```
bar
```
baz

```

```html
<p>foo</p>
<pre><code>bar
</code></pre>
<p>baz</p>

```

--------------------------------

### Link reference inside blockquote ambiguity

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Shows a blockquote containing a link reference definition to illustrate the ambiguity of whether link references can be defined inside block quotes or list items.

```markdown
> Blockquote [foo].
>
> [foo]: /url
```

--------------------------------

### cmark_node_set_list_start

Source: https://github.com/commonmark/cmark/blob/master/man/man3/cmark.3

Sets starting number of the node, if it is an ordered list. Returns 1 on success, 0 on failure.

```APIDOC
## cmark_node_set_list_start

### Description
Sets starting number of the node, if it is an ordered list. Returns 1 on success, 0 on failure.

### Signature
`int cmark_node_set_list_start(cmark_node *node, int start)`

### Parameters
- **node** (cmark_node*) - Required - The node to modify.
- **start** (int) - Required - The starting number to set.

### Returns
- **int** - 1 on success, 0 on failure.
```

--------------------------------

### Build cmark_exe executable

Source: https://github.com/commonmark/cmark/blob/master/src/CMakeLists.txt

Creates the cmark command-line executable from main.c, applies compile options, sets output name to "cmark" and install RPATH to Base_rpath, and links it privately to the cmark library.

```cmake
add_executable(cmark_exe
  main.c)
cmark_add_compile_options(cmark_exe)
set_target_properties(cmark_exe PROPERTIES
  OUTPUT_NAME "cmark"
  INSTALL_RPATH "${Base_rpath}")
target_link_libraries(cmark_exe PRIVATE
  cmark)
```

--------------------------------

### List marker type change ambiguity

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Shows a list where markers change from numbers to bullets to illustrate the ambiguity of whether it is two lists or one.

```markdown
1. fee
2. fie
-  foe
-  fum
```

--------------------------------

### Fenced code block between other blocks without blank lines

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

A fenced code block can appear between other blocks (like headings and thematic breaks) without intervening blank lines.

```markdown
foo
---
~~~
bar
~~~
# baz

```

```html
<h2>foo</h2>
<pre><code>bar
</code></pre>
<h1>baz</h1>

```

--------------------------------

### Info strings for tilde code blocks can contain backticks and tildes

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Tilde code blocks allow backticks and tildes in the info string; the first word is used as the language.

```markdown
~~~ aa ``` ~~~
foo
~~~

```

```html
<pre><code class="language-aa">foo
</code></pre>

```

--------------------------------

### Indented list markers ambiguity

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Shows list markers with varying indentation to illustrate the ambiguity of whether list markers can be indented and whether ordered list markers can be right-aligned.

```markdown
 8. item 1
 9. item 2
10. item 2a
```

--------------------------------

### Thematic break in list ambiguity

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Shows a list with a thematic break in its second item to illustrate the ambiguity of whether it is one list or two lists separated by a thematic break.

```markdown
* a
* * * * *
* b
```

--------------------------------

### Tilde code fence with internal spaces is not a closing fence

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

A tilde code fence with internal spaces is not recognized as a closing fence, so the content remains inside the code block.

```markdown
~~~~~~
aaa
~~~ ~~

```

```html
<pre><code>aaa
~~~ ~~
</code></pre>

```

--------------------------------

### Fenced code block with closing fence indented 4 spaces is not a closing fence

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

A closing fence indented four spaces is not recognized as a closing fence, so the content remains inside the code block.

```markdown
```
aaa
    ```

```

```html
<pre><code>aaa
    ```
</code></pre>

```

--------------------------------

### Info strings for backtick code blocks cannot contain backticks

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

If a backtick code block's info string contains backticks, it is not treated as a code block; it becomes inline code.

```markdown
``` aa ```
foo

```

```html
<p><code>aa</code>
foo</p>

```

--------------------------------

### CMakeLists.txt top-level configuration for cmark

Source: https://github.com/commonmark/cmark/blob/master/CMakeLists.txt

Top-level CMakeLists.txt for the cmark project. Sets project version 0.31.2, C standard (C23 if CMake >= 3.21, else C11), disables compiler extensions, includes required modules (CMakePackageConfigHelpers, CTest, GenerateExportHeader, GNUInstallDirs), and defines build options like CMARK_LIB_FUZZER and BUILD_SHARED_LIBS. Also sets visibility hidden, install RPATH handling, and adds compile options for Debug, Profile, Ubsan, and fuzzing configurations.

```CMake
cmake_minimum_required(VERSION 3.14)

project(cmark
  LANGUAGES C CXX
  VERSION 0.31.2)

if(CMAKE_VERSION VERSION_GREATER_EQUAL 3.21)
  set(CMAKE_C_STANDARD 23)
else()
  set(CMAKE_C_STANDARD 11)
endif()
set(CMAKE_C_EXTENSIONS NO)

if(CMAKE_BUILD_TYPE STREQUAL Asan)
  list(APPEND CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake/modules)
  include(FindAsan)
endif()

# Include module for functions
# - 'write_basic_package_version_file'
# - 'configure_package_config_file'
include(CMakePackageConfigHelpers)
include(CTest)
include(GenerateExportHeader)
include(GNUInstallDirs)

if(NOT MSVC OR CMAKE_HOST_SYSTEM_NAME STREQUAL Windows)
  set(CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_NO_WARNINGS ON)
  include(InstallRequiredSystemLibraries)
endif()

if("${CMAKE_SOURCE_DIR}" STREQUAL "${CMAKE_BINARY_DIR}")
    message(FATAL_ERROR "Do not build in-source.\nPlease remove CMakeCache.txt and the CMakeFiles/ directory.\nThen: mkdir build ; cd build ; cmake .. ; make")
endif()

# Backwards Compatibility
# TODO: remove this once there has been a period to enable people to migrate
set(_CMARK_BUILD_SHARED_LIBS_DEFAULT NO)
if(DEFINED CMARK_SHARED)
  message(AUTHOR_WARNING [=[
'CMARK_SHARED' has been replaced with the standard 'BUILD_SHARED_LIBS' to control the library type.
]=])
  set(_CMARK_BUILD_SHARED_LIBS_DEFAULT ${CMARK_SHARED})
endif()
if(DEFINED CMARK_STATIC)
  message(AUTHOR_WARNING [=[
'CMARK_STATIC' has been replaced with the standard 'BUILD_SHARED_LIBS' to control the library type.
]=])
  if(NOT CMARK_STATIC)
    set(_CMARK_BUILD_SHARED_LIBS_DEFAULT YES)
  else()
    set(_CMARK_BUILD_SHARED_LIBS_DEFAULT NO)
  endif()
endif()

option(CMARK_LIB_FUZZER "Build libFuzzer fuzzing harness" OFF)
option(BUILD_SHARED_LIBS "Build the CMark library as shared"
  ${_CMARK_BUILD_SHARED_LIBS_DEFAULT})

# -fvisibility=hidden
set(CMAKE_C_VISIBILITY_PRESET hidden)
set(CMAKE_VISIBILITY_INLINES_HIDDEN 1)

set(CMAKE_INCLUDE_CURRENT_DIR ON)

if (DEFINED CMAKE_INSTALL_RPATH)
  set(Base_rpath "${CMAKE_INSTALL_RPATH}")
else()
  if(BUILD_SHARED_LIBS)
    set(p "${CMAKE_INSTALL_FULL_LIBDIR}")
    list(FIND CMAKE_PLATFORM_IMPLICIT_LINK_DIRECTORIES "${p}" i)
    if("${i}" STREQUAL "-1")
      set(Base_rpath "${p}")
    endif()
  endif()
endif()

# Append non-standard external dependency directories, if any.
set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)

# Check integrity of node structure when compiled as debug
add_compile_options($<$<CONFIG:Debug>:-DCMARK_DEBUG_NODES>)

# In order to maintain compatibility with older platforms which may not have a
# recent version of CMake (i.e. are running CMake <3.3), we cannot simply use
# the `add_compile_options` with a generator expression.  This uses the
# `target_compile_options` with `PRIVATE` to add the flags only to the targets
# so that CMark may be used in projects with non-C languages.
function(cmark_add_compile_options target)
  if(MSVC)
    target_compile_definitions(${target} PRIVATE _CRT_SECURE_NO_WARNINGS)
  else()
    target_compile_options(${target} PRIVATE
            -Wall -Wextra -pedantic
            $<$<COMPILE_LANGUAGE:C>:-Wstrict-prototypes>)
  endif()
  if(CMAKE_BUILD_TYPE STREQUAL Profile)
    target_compile_options(${target} PRIVATE -pg)
  endif()
  if(CMAKE_BUILD_TYPE STREQUAL Ubsan)
    target_compile_options(${target} PRIVATE -fsanitize=undefined)
  endif()
  if(CMARK_LIB_FUZZER)
    if(target MATCHES fuzz)
      target_compile_options(${target} PRIVATE -fsanitize=fuzzer)
      target_link_options(${target} PRIVATE -fsanitize=fuzzer)
    else()
      target_compile_options(${target} PRIVATE -fsanitize=fuzzer-no-link)
      target_link_options(${target} PRIVATE -fsanitize=fuzzer-no-link)
    endif()
  endif()
endfunction()

add_subdirectory(src)
# TODO(compnerd) should this be enabled for MinGW, which sets CMAKE_SYSTEM_NAME
# to Windows, but defines `MINGW`.
if(NOT CMAKE_SYSTEM_NAME STREQUAL Windows)
  add_subdirectory(man)
endif()
if(BUILD_TESTING)
  add_subdirectory(api_test)
  add_subdirectory(test testdir)
endif()
if(CMARK_LIB_FUZZER)
  add_subdirectory(fuzz)
endif()

if(NOT CMAKE_BUILD_TYPE)
  set(CMAKE_BUILD_TYPE "Release" CACHE STRING
  "Choose the type of build, options are: Debug Profile Release Asan Ubsan." FORCE)
endif(NOT CMAKE_BUILD_TYPE)
```

--------------------------------

### Intraword emphasis with asterisks vs underscores

Source: https://github.com/commonmark/cmark/blob/master/test/spec.txt

Many implementations restrict intraword emphasis to the * forms to avoid unwanted emphasis in words containing internal underscores. It is best practice to put these in code spans.

```markdown
internal emphasis: foo*bar*baz
no emphasis: foo_bar_baz
```

--------------------------------

### kramdown pathological input command

Source: https://github.com/commonmark/cmark/blob/master/why-cmark-and-not-x.md

Shows the command used to generate pathological input that causes kramdown to get tied in knots. The input consists of 50,000 opening brackets, an 'a', and 50,000 closing brackets.

```shell
python -c 'print(("[" * 50000) + "a" + ("]" * 50000))'
```

--------------------------------

### CMake test setup for cmark

Source: https://github.com/commonmark/cmark/blob/master/test/CMakeLists.txt

Configures CTest tests for the cmark project. Requires Python 3 for spec tests unless SPEC_TESTS is set. Adds tests for HTML normalization, spec tests, pathological tests, roundtrip tests, entity tests, and smart punctuation tests.

```cmake
# To get verbose output: cmake --build build --target "test" -- ARGS='-V'

# By default, we run the spec tests only if python3 is available.
# To require the spec tests, compile with -DSPEC_TESTS=1

if(SPEC_TESTS)
  set(PYTHON_REQUIRED REQUIRED)
else()
  set(PYTHON_REQUIRED)
endif()

find_package(Python3 ${PYTHON_REQUIRED} COMPONENTS Interpreter)

IF (Python3_Interpreter_FOUND)

  add_test(NAME html_normalization
           COMMAND "$<TARGET_FILE:Python3::Interpreter>" -m doctest "${CMAKE_CURRENT_SOURCE_DIR}/normalize.py")

  if(BUILD_SHARED_LIBS)
    add_test(NAME spectest_library
             COMMAND "$<TARGET_FILE:Python3::Interpreter>" "${CMAKE_CURRENT_SOURCE_DIR}/spec_tests.py"
                                                           --no-normalize
                                                           --spec "${CMAKE_CURRENT_SOURCE_DIR}/spec.txt"
                                                           --library-dir "$<TARGET_FILE_DIR:cmark>")

    add_test(NAME pathological_tests_library
             COMMAND "$<TARGET_FILE:Python3::Interpreter>" "${CMAKE_CURRENT_SOURCE_DIR}/pathological_tests.py"
                                                           --library-dir "$<TARGET_FILE_DIR:cmark>")

    add_test(NAME roundtriptest_library
             COMMAND "$<TARGET_FILE:Python3::Interpreter>" "${CMAKE_CURRENT_SOURCE_DIR}/roundtrip_tests.py"
                                                           --spec "${CMAKE_CURRENT_SOURCE_DIR}/spec.txt"
                                                           --library-dir "$<TARGET_FILE_DIR:cmark>")

    add_test(NAME entity_library
             COMMAND "$<TARGET_FILE:Python3::Interpreter>" "${CMAKE_CURRENT_SOURCE_DIR}/entity_tests.py"
                                                           --library-dir "$<TARGET_FILE_DIR:cmark>")
  endif()

  add_test(NAME spectest_executable
           COMMAND "$<TARGET_FILE:Python3::Interpreter>" "${CMAKE_CURRENT_SOURCE_DIR}/spec_tests.py"
                                                         --no-normalize
                                                         --spec "${CMAKE_CURRENT_SOURCE_DIR}/spec.txt"
                                                         --program "$<TARGET_FILE:cmark_exe>")

  add_test(NAME smartpuncttest_executable
           COMMAND "$<TARGET_FILE:Python3::Interpreter>" "${CMAKE_CURRENT_SOURCE_DIR}/spec_tests.py"
                                                         --no-normalize
                                                         --spec "${CMAKE_CURRENT_SOURCE_DIR}/smart_punct.txt"
                                                         --program "$<TARGET_FILE:cmark_exe> --smart")

  add_test(NAME regressiontest_executable
           COMMAND "$<TARGET_FILE:Python3::Interpreter>" "${CMAKE_CURRENT_SOURCE_DIR}/spec_tests.py"
                                                         --no-normalize
                                                         --spec "${CMAKE_CURRENT_SOURCE_DIR}/regression.txt"
                                                         --program "$<TARGET_FILE:cmark_exe>")

ELSE(Python3_Interpreter_FOUND)

  message(WARNING "A Python 3 Interpreter is required to run the spec tests")

ENDIF(Python3_Interpreter_FOUND)
```

--------------------------------

### cmark_iter_new

Source: https://github.com/commonmark/cmark/blob/master/man/man3/cmark.3

Creates a new iterator starting at the given root node. The current node and event type are undefined until cmark_iter_next is called for the first time. The memory allocated for the iterator should be released using cmark_iter_free when it is no longer needed.

```APIDOC
## cmark_iter_new

### Description
Creates a new iterator starting at the given root node. The current node and event type are undefined until cmark_iter_next is called for the first time. The memory allocated for the iterator should be released using cmark_iter_free when it is no longer needed.

### Signature
```c
cmark_iter *cmark_iter_new(cmark_node *root)
```

### Parameters
- **root** (cmark_node*) - Required - The root node to start iterating from.

### Return Value
- **cmark_iter*** - A pointer to the newly created iterator.
```

--------------------------------

### Configure version and pkg-config files

Source: https://github.com/commonmark/cmark/blob/master/src/CMakeLists.txt

Generates cmark_version.h and libcmark.pc from templates using configure_file. The .pc file uses @ONLY to substitute only @VAR@ references.

```cmake
configure_file(cmark_version.h.in
  ${CMAKE_CURRENT_BINARY_DIR}/cmark_version.h)
configure_file(libcmark.pc.in
  ${CMAKE_CURRENT_BINARY_DIR}/libcmark.pc
  @ONLY)
```

--------------------------------

### Create release tarball and zip archive

Source: https://github.com/commonmark/cmark/blob/master/README.md

Makes a release tarball and zip archive.

```shell
make archive
```

--------------------------------

### Run detailed benchmark with make newbench

Source: https://github.com/commonmark/cmark/blob/master/README.md

Runs more detailed benchmarks using the GNU Makefile.

```shell
make newbench
```

--------------------------------

### Run benchmark with make bench

Source: https://github.com/commonmark/cmark/blob/master/README.md

Runs a benchmark using the GNU Makefile. Requires GNU make and cmake.

```shell
make bench
```

--------------------------------

### Run fuzz test with make fuzztest

Source: https://github.com/commonmark/cmark/blob/master/README.md

Runs a fuzz test against ten long randomly generated inputs.

```shell
make fuzztest
```

--------------------------------

### Run libFuzzer fuzzing

Source: https://github.com/commonmark/cmark/blob/master/README.md

Runs the fuzzer with libFuzzer support.

```shell
make libFuzzer
```

--------------------------------

### cmark_node_get_start_line

Source: https://github.com/commonmark/cmark/blob/master/man/man3/cmark.3

Returns the line on which the node begins.

```APIDOC
## cmark_node_get_start_line

### Description
Returns the line on which the node begins.

### Signature
`int cmark_node_get_start_line(cmark_node *node)`

### Parameters
- **node** (cmark_node*) - Required - The node to query.

### Returns
- **int** - The line on which the node begins.
```

--------------------------------

### Reformat source code with clang-format

Source: https://github.com/commonmark/cmark/blob/master/README.md

Reformats source code using clang-format. Requires clang-format to be available.

```shell
make format
```

--------------------------------

### cmark_parser_new_with_mem is approximately cmark_parser_new_with_mem_into_root with a new document node

Source: https://github.com/commonmark/cmark/blob/master/man/man3/cmark.3

Shows that cmark_parser_new_with_mem(options, mem) is approximately the same as calling cmark_parser_new_with_mem_into_root with a newly created document node. This is useful for building a single document from multiple parsed fragments.

```c
cmark_parser_new_with_mem(options, mem)
```

```c
cmark_parser_new_with_mem_into_root(options, mem, cmark_node_new(CMARK_NODE_DOCUMENT))
```

--------------------------------

### Cross-compile Windows binary on Linux

Source: https://github.com/commonmark/cmark/blob/master/README.md

Cross-compiles a Windows binary and dll on Linux using the mingw32 compiler. The binaries will be in build-mingw/windows/bin.

```shell
make mingw
```

--------------------------------

### cmark_parser_new is equivalent to cmark_parser_new_with_mem with default allocator

Source: https://github.com/commonmark/cmark/blob/master/man/man3/cmark.3

Shows that cmark_parser_new(options) is the same as calling cmark_parser_new_with_mem with cmark_get_default_mem_allocator(). Use this when you need a custom memory allocator.

```c
cmark_parser_new(options)
```

```c
cmark_parser_new_with_mem(options, cmark_get_default_mem_allocator())
```

--------------------------------

### Generate Xcode project files on OSX

Source: https://github.com/commonmark/cmark/blob/master/README.md

Creates an Xcode project for building cmark on macOS. The project file is build/cmark.xcodeproj.

```shell
cmake -S . -B build -G Xcode
open build/cmark.xcodeproj
```

--------------------------------

### Run systematic fuzz test with AFL

Source: https://github.com/commonmark/cmark/blob/master/README.md

Runs a more systematic fuzz test using american fuzzy lop. Set AFL_PATH to the AFL directory.

```shell
AFL_PATH=/path/to/afl_directory make afl
```

--------------------------------

### CMakeLists.txt for api_test executable

Source: https://github.com/commonmark/cmark/blob/master/api_test/CMakeLists.txt

Defines the api_test executable from cplusplus.cpp, harness.c, harness.h, and main.c. Applies cmark_add_compile_options, links the cmark library privately, and registers a CTest test named api_test. On Windows, sets the test environment PATH to include the cmark target's directory so the DLL is found at runtime.

```CMake
add_executable(api_test
  cplusplus.cpp
  harness.c
  harness.h
  main.c
)
cmark_add_compile_options(api_test)
target_link_libraries(api_test PRIVATE
  cmark)

add_test(NAME api_test COMMAND api_test)
if(WIN32)
  set_tests_properties(api_test PROPERTIES
    ENVIRONMENT "PATH=$<TARGET_FILE_DIR:cmark>$<SEMICOLON>$ENV{PATH}")
endif()
```

--------------------------------

### Compile with MSVC and NMAKE

Source: https://github.com/commonmark/cmark/blob/master/README.md

Compiles cmark on Windows using MSVC and NMAKE.

```shell
nmake /f Makefile.nmake
```

--------------------------------

### cmark_parser_new_with_mem_into_root

Source: https://github.com/commonmark/cmark/blob/master/man/man3/cmark.3

Creates a new parser object with a given node to use as the root of the parsed AST. Useful for creating a single document from multiple fragments.

```APIDOC
## cmark_parser_new_with_mem_into_root

### Description
Creates a new parser object with the given node to use as the root node of the parsed AST. When parsing, children are always appended, not prepended; that means if root already has children, the newly-parsed children will appear after the given children. A generalization of cmark_parser_new_with_mem: cmark_parser_new_with_mem(options, mem) is approximately the same as cmark_parser_new_with_mem_into_root(options, mem, cmark_node_new(CMARK_NODE_DOCUMENT)). This is useful for creating a single document out of multiple parsed document fragments.

### Signature
cmark_parser *cmark_parser_new_with_mem_into_root(int options, cmark_mem *mem, cmark_node *root)

### Parameters
- **options** (int) - Required - Parser options.
- **mem** (cmark_mem*) - Required - Memory allocator.
- **root** (cmark_node*) - Required - The root node to use.

### Returns
- **cmark_parser*** - A new parser object.
```

--------------------------------

### cmark_node_get_start_column

Source: https://github.com/commonmark/cmark/blob/master/man/man3/cmark.3

Returns the column at which the node begins.

```APIDOC
## cmark_node_get_start_column

### Description
Returns the column at which the node begins.

### Signature
`int cmark_node_get_start_column(cmark_node *node)`

### Parameters
- **node** (cmark_node*) - Required - The node to query.

### Returns
- **int** - The column at which the node begins.
```

--------------------------------

### cmark_node_new_with_mem

Source: https://github.com/commonmark/cmark/blob/master/man/man3/cmark.3

Same as cmark_node_new, but explicitly listing the memory allocator used to allocate the node. Note: be sure to use the same allocator for every node in a tree, or bad things can happen.

```APIDOC
## cmark_node_new_with_mem

### Description
Same as cmark_node_new, but explicitly listing the memory allocator used to allocate the node. Note: be sure to use the same allocator for every node in a tree, or bad things can happen.

### Signature
_cmark_node *_ **cmark_node_new_with_mem**(_cmark_node_type type_, _cmark_mem *mem_)

### Parameters
- **type** (cmark_node_type) - Required - The type of the new node.
- **mem** (cmark_mem*) - Required - The memory allocator to use.

### Return Value
- **cmark_node*** - A pointer to the newly created node.
```

--------------------------------

### cmark_parser_new_with_mem

Source: https://github.com/commonmark/cmark/blob/master/man/man3/cmark.3

Creates a new parser object with a given memory allocator. Generalizes cmark_parser_new.

```APIDOC
## cmark_parser_new_with_mem

### Description
Creates a new parser object with the given memory allocator. A generalization of cmark_parser_new: cmark_parser_new(options) is the same as cmark_parser_new_with_mem(options, cmark_get_default_mem_allocator()).

### Signature
cmark_parser *cmark_parser_new_with_mem(int options, cmark_mem *mem)

### Parameters
- **options** (int) - Required - Parser options.
- **mem** (cmark_mem*) - Required - Memory allocator.

### Returns
- **cmark_parser*** - A new parser object.
```

--------------------------------

### Define cmark library target

Source: https://github.com/commonmark/cmark/blob/master/src/CMakeLists.txt

Creates the cmark static/shared library from all source files. Applies cmark_add_compile_options, sets output name to "cmark", enables position-independent code, and sets SOVERSION/VERSION to PROJECT_VERSION. When BUILD_SHARED_LIBS is OFF, defines CMARK_STATIC_DEFINE publicly.

```cmake
add_library(cmark
  blocks.c
  buffer.c
  cmark.c
  cmark_ctype.c
  commonmark.c
  houdini_href_e.c
  houdini_html_e.c
  houdini_html_u.c
  html.c
  inlines.c
  iterator.c
  latex.c
  man.c
  node.c
  references.c
  render.c
  scanners.c
  scanners.re
  utf8.c
  xml.c)
cmark_add_compile_options(cmark)
set_target_properties(cmark PROPERTIES
  OUTPUT_NAME "cmark"
  # Avoid name clash between PROGRAM and LIBRARY pdb files.
  PDB_NAME libcmark
  POSITION_INDEPENDENT_CODE YES
  # Include minor version and patch level in soname for now.
  SOVERSION ${PROJECT_VERSION}
  VERSION ${PROJECT_VERSION})
if(NOT BUILD_SHARED_LIBS)
  target_compile_definitions(cmark PUBLIC
    CMARK_STATIC_DEFINE)
endif()
target_include_directories(cmark INTERFACE
  $<INSTALL_INTERFACE:include>
  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
  $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>)
```

--------------------------------

### cmark_parser_new

Source: https://github.com/commonmark/cmark/blob/master/man/man3/cmark.3

Creates a new parser object.

```APIDOC
## cmark_parser_new

### Description
Creates a new parser object.

### Signature
cmark_parser *cmark_parser_new(int options)

### Parameters
- **options** (int) - Required - Parser options.

### Returns
- **cmark_parser*** - A new parser object.
```

--------------------------------

### cmark_version_string

Source: https://github.com/commonmark/cmark/blob/master/man/man3/cmark.3

Returns the library version as a string for runtime checks. This is useful for displaying the version to users or for logging purposes.

```APIDOC
## cmark_version_string

### Description
Returns the library version as a string for runtime checks. This is useful for displaying the version to users or for logging purposes.

### Method
Function

### Signature
`const char *cmark_version_string(void)`

### Return Value
- **const char \*** - The library version string.
```

--------------------------------

### Iterate over cmark AST with cmark_iter_new and cmark_iter_next

Source: https://github.com/commonmark/cmark/blob/master/man/man3/cmark.3

Walks a cmark node tree from a root node, returning ENTER/EXIT events for each node. Use this to render HTML or transform the AST. The iterator must be freed with cmark_iter_free. EXIT events are never returned for leaf nodes.

```c
void
usage_example(cmark_node *root) {

    cmark_event_type ev_type;

    cmark_iter *iter = cmark_iter_new(root);

    while ((ev_type = cmark_iter_next(iter)) != CMARK_EVENT_DONE) {

        cmark_node *cur = cmark_iter_get_node(iter);

        // Do something with `cur` and `ev_type`

    }

    cmark_iter_free(iter);
}
```

--------------------------------

### Generate export header and static target alias

Source: https://github.com/commonmark/cmark/blob/master/src/CMakeLists.txt

Generates cmark_export.h via generate_export_header with BASE_NAME ${PROJECT_NAME}. Adds a custom target cmark_static that depends on cmark to provide a migration path for OSS Fuzz.

```cmake
generate_export_header(cmark
  BASE_NAME ${PROJECT_NAME})

# FIXME(compnerd) this should be removed, but exists solely to allow a migration
# path for OSS Fuzz.
add_custom_target(cmark_static DEPENDS cmark)
```

--------------------------------

### Streaming parse with cmark_parser_new, cmark_parser_feed, and cmark_parser_finish

Source: https://github.com/commonmark/cmark/blob/master/man/man3/cmark.3

Parses a file incrementally using the streaming interface. Create a parser with cmark_parser_new, feed it chunks from a file, then finish with cmark_parser_finish and free the parser with cmark_parser_free. The loop reads until fewer bytes than the buffer size are returned.

```c
cmark_parser *parser = cmark_parser_new(CMARK_OPT_DEFAULT);
FILE *fp = fopen("myfile.md", "rb");
while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0) {

    cmark_parser_feed(parser, buffer, bytes);

    if (bytes < sizeof(buffer)) {

        break;

    }
}
document = cmark_parser_finish(parser);
cmark_parser_free(parser);
```

--------------------------------

### Benchmark cmark vs hoedown on pathological input

Source: https://github.com/commonmark/cmark/blob/master/why-cmark-and-not-x.md

Compares cmark and hoedown processing 50,000 unmatched brackets. cmark finishes in 0.073s while hoedown takes 17.84s, illustrating hoedown's vulnerability to pathological input despite its DOS protection claims.

```shell
% time python -c 'print(("[" * 50000) + "a" + ("]" * 50000))' | cmark
...
user 0m0.073s
```

```shell
% time python -c 'print(("[" * 50000) + "a" + ("]" * 50000))' | hoedown
...
0m17.84s
```

--------------------------------

### hoedown parsing bug: case-sensitive link reference

Source: https://github.com/commonmark/cmark/blob/master/why-cmark-and-not-x.md

Shows hoedown failing to match a link reference definition with different case. The definition uses Greek uppercase letters while the reference uses lowercase, and hoedown does not resolve the link.

```shell
% hoedown
[ΑΓΩ]: /φου

[αγω]
^D
<p>[αγω]</p>
```

--------------------------------

### cmark_render_man

Source: https://github.com/commonmark/cmark/blob/master/man/man3/cmark.3

Renders a node tree as a groff man page without the header. The caller is responsible for freeing the returned buffer.

```APIDOC
## cmark_render_man

### Description
Renders a node tree as a groff man page without the header. The caller is responsible for freeing the returned buffer.

### Signature
`char *cmark_render_man(cmark_node *root, int options, int width)`

### Parameters
- **root** (cmark_node*) - Required - The root node of the tree to render.
- **options** (int) - Required - Rendering options (see Options section).
- **width** (int) - Required - The width for the man page.

### Return Value
- **char*** - A pointer to the rendered man page. The caller must free it.
```

--------------------------------

### cmark_node_set_on_enter

Source: https://github.com/commonmark/cmark/blob/master/man/man3/cmark.3

Sets the literal text to render "on enter" for a custom node. Any children of the node will be rendered after this text. Returns 1 on success 0 on failure.

```APIDOC
## cmark_node_set_on_enter

### Description
Sets the literal text to render "on enter" for a custom node. Any children of the node will be rendered after this text. Returns 1 on success 0 on failure.

### Signature
`int cmark_node_set_on_enter(cmark_node *node, const char *on_enter)`

### Parameters
- **node** (cmark_node*) - Required - The node to modify.
- **on_enter** (const char*) - Required - The literal text to render on enter.

### Returns
- **int** - 1 on success, 0 on failure.
```

--------------------------------

### cmark_node_get_on_enter

Source: https://github.com/commonmark/cmark/blob/master/man/man3/cmark.3

Returns the literal "on enter" text for a custom node, or an empty string if no on_enter is set. Returns NULL if called on a non-custom node.

```APIDOC
## cmark_node_get_on_enter

### Description
Returns the literal "on enter" text for a custom node, or an empty string if no on_enter is set. Returns NULL if called on a non-custom node.

### Signature
`const char *cmark_node_get_on_enter(cmark_node *node)`

### Parameters
- **node** (cmark_node*) - Required - The node to query.

### Returns
- **const char*** - The "on enter" text, or an empty string if none set. NULL if not a custom node.
```

--------------------------------

### CMake target definition for cmark-fuzz

Source: https://github.com/commonmark/cmark/blob/master/fuzz/CMakeLists.txt

Defines the cmark-fuzz executable from cmark-fuzz.c, applies common compile options via cmark_add_compile_options, and links it against the cmark library.

```CMake
add_executable(cmark-fuzz cmark-fuzz.c)
cmark_add_compile_options(cmark-fuzz)
target_link_libraries(cmark-fuzz cmark)
```
Tokens:
Raw