README.md (6878B)
1 [](https://travis-ci.org/mity/md4c)
2 [](https://ci.appveyor.com/project/mity/md4c/branch/master)
3 [](https://scan.coverity.com/projects/mity-md4c)
4 [](https://codecov.io/github/mity/md4c)
5
6 # MD4C Readme
7
8 * Home: http://github.com/mity/md4c
9 * Wiki: http://github.com/mity/md4c/wiki
10
11 MD4C stands for "Markdown for C" and, unsurprisingly, it is a C Markdown parser
12 implementation.
13
14
15 ## What is Markdown
16
17 In short, Markdown is the markup language this `README.md` file is written in.
18
19 The following resources can explain more if you are unfamiliar with it:
20 * [Wikipedia article](http://en.wikipedia.org/wiki/Markdown)
21 * [CommonMark site](http://commonmark.org)
22
23
24 ## What is MD4C
25
26 MD4C is C Markdown parser with the following features:
27
28 * **Compliance:** Generally MD4C aims to be compliant to the latest version of
29 [CommonMark specification](http://spec.commonmark.org/). Right now we are
30 fully compliant to CommonMark 0.28.
31
32 * **Extensions:** MD4C supports some commonly requested and accepted extensions.
33 See below.
34
35 * **Compactness:** MD4C is implemented in one source file and one header file.
36
37 * **Embedding:** MD4C is easy to reuse in other projects, its API is very
38 straightforward: There is actually just one function, `md_parse()`.
39
40 * **Push model:** MD4C parses the complete document and calls callback
41 functions provided by the application for each start/end of block, start/end
42 of a span, and with any textual contents.
43
44 * **Portability:** MD4C builds and works on Windows and Linux, and it should
45 be fairly simple to make it run also on most other systems.
46
47 * **Encoding:** MD4C can be compiled to recognize ASCII-only control characters,
48 UTF-8 and, on Windows, also UTF-16, i.e. what is on Windows commonly called
49 just "Unicode". See more details below.
50
51 * **Permissive license:** MD4C is available under the MIT license.
52
53 * **Performance:** MD4C is very fast. Preliminary tests show it's quite faster
54 then [Hoedown](https://github.com/hoedown/hoedown) or
55 [Cmark](https://github.com/jgm/cmark).
56
57
58 ## Using MD4C
59
60 The parser is implemented in a single C source file `md4c.c` and its
61 accompanying header `md4c.h`.
62
63 The main provided function is `md_parse()`. It takes a text in Markdown syntax
64 as an input and a pointer to renderer structure which holds pointers to few
65 callback functions.
66
67 As `md_parse()` processes the input, it calls the appropriate callbacks
68 allowing application to convert it into another format or render it onto
69 the screen.
70
71 More comprehensive guide can be found in the header `md4c.h` and also
72 on [MD4C wiki](http://github.com/mity/md4c/wiki).
73
74 Example implementation of simple renderer is available in the `md2html`
75 directory which implements a conversion utility from Markdown to HTML.
76
77
78 ## Markdown Extensions
79
80 The default behavior is to recognize only elements defined by the [CommonMark
81 specification](http://spec.commonmark.org/).
82
83 However with appropriate renderer flags, the behavior can be tuned to enable
84 some extensions or allowing some deviations from the specification.
85
86 * With the flag `MD_FLAG_COLLAPSEWHITESPACE`, non-trivial whitespace is
87 collapsed into a single space.
88
89 * With the flag `MD_FLAG_TABLES`, GitHub-style tables are supported.
90
91 * With the flag `MD_FLAG_STRIKETHROUGH`, strikethrough spans are enabled
92 (text enclosed in tilde marks, e.g. '~foo bar~').
93
94 * With the flag `MD_FLAG_PERMISSIVEURLAUTOLINKS` permissive URL autolinks
95 (not enclosed in `<` and `>`) are supported.
96
97 * With the flag `MD_FLAG_PERMISSIVEAUTOLINKS`, ditto for e-mail autolinks.
98
99 * With the flag `MD_FLAG_PERMISSIVEWWWAUTOLINKS` permissive WWW autolinks
100 (without any scheme specified; `http:` is assumed) are supported.
101
102 * With the flag `MD_FLAG_NOHTMLSPANS` or `MD_FLAG_NOHTML`, raw inline HTML
103 or raw HTML blocks respectively are disabled.
104
105 * With the flag `MD_FLAG_NOINDENTEDCODEBLOCKS`, indented code blocks are
106 disabled.
107
108
109 ## Input/Output Encoding
110
111 The CommonMark specification generally assumes UTF-8 input, but under closer
112 inspection, Unicode plays any role in few very specific situations when parsing
113 Markdown documents:
114
115 * For detection of word boundary when processing emphasis and strong emphasis,
116 some classification of Unicode character (whitespace, punctuation) is used.
117
118 * For (case-insensitive) matching of a link reference with corresponding link
119 reference definition, Unicode case folding is used.
120
121 * For translating HTML entities (e.g. `&`) and numeric character
122 references (e.g. `#` or `ಫ`) into their Unicode equivalents.
123 However MD4C leaves this translation on the renderer/application; as the
124 renderer is supposed to really know output encoding and whether it really
125 needs to perform this kind of translation. (Consider that a renderer
126 converting Markdown to HTML may leave the entities untranslated and defer
127 the work to a web browser.)
128
129 MD4C relies on this property of the CommonMark and the implementation is, to
130 a large degree, encoding-agnostic. Most of MD4C code only assumes that the
131 encoding of your choice is compatible with ASCII, i.e. that the codepoints
132 below 128 have the same numeric values as ASCII.
133
134 Any input MD4C does not understand is simply seen as part of the document text
135 and sent to the renderer's callback functions unchanged.
136
137 The two situations where MD4C has to understand Unicode are handled accordingly
138 to the following preprocessor macros:
139
140 * If preprocessor macro `MD4C_USE_UTF8` is defined, MD4C assumes UTF-8
141 for word boundary detection and case-folding.
142
143 * On Windows, if preprocessor macro `MD4C_USE_UTF16` is defined, MD4C uses
144 `WCHAR` instead of `char` and assumes UTF-16 encoding in those situations.
145 (UTF-16 is what Windows developers usually call just "Unicode" and what
146 Win32API works with.)
147
148 * By default (when none of the macros is defined), ASCII-only mode is used
149 even in the specific situations. That effectively means that non-ASCII
150 whitespace or punctuation characters won't be recognized as such and that
151 case-folding is performed only on ASCII letters (i.e. `[a-zA-Z]`).
152
153 (Adding support for yet another encodings should be relatively simple due
154 the isolation of the respective code.)
155
156
157 ## License
158
159 MD4C is covered with MIT license, see the file `LICENSE.md`.
160
161
162 ## Reporting Bugs
163
164 If you encounter any bug, please be so kind and report it. Unheard bugs cannot
165 get fixed. You can submit bug reports here:
166
167 * http://github.com/mity/md4c/issues