README.rst
1cmarkgfm - Python bindings to GitHub's cmark
2============================================
3
4Minimalist Python bindings to GitHub's fork of cmark.
5
6Installation
7------------
8
9This package is published on PyPI as `cmarkgfm <https://pypi.org/project/cmarkgfm/>`__
10and can be installed with `pip` or `pipenv`::
11
12 pip install --user cmarkgfm
13 pipenv install cmarkgfm
14
15Wheels are provided for macOS, Linux, and Windows for Python 2.7\*, 3.5, 3.6, 3.7, 3.8 and 3.9.
16
17\* Python 2.7 is not supported on Windows and will only be supported on other platforms so long as `cibuildwheel <https://cibuildwheel.readthedocs.io/en/stable/>`__ continues to support them.
18
19
20Usage
21-----
22
23High-level usage is really straightforward. To render normal CommonMark
24markdown:
25
26.. code-block:: python
27
28 import cmarkgfm
29
30 html = cmarkgfm.markdown_to_html(markdown_text)
31
32
33To render GitHub-flavored markdown:
34
35.. code-block:: python
36
37 import cmarkgfm
38
39 html = cmarkgfm.github_flavored_markdown_to_html(markdown_text)
40
41
42Advanced Usage
43--------------
44
45**Options**
46
47Both rendering methods ``markdown_to_html`` and ``github_flavored_markdown_to_html`` have
48an optional ``options`` argument that can be used to activate `options of cmark <https://manpages.debian.org/stretch/cmark/cmark.1.en.html>`_.
49For example:
50
51.. code-block:: python
52
53 import cmarkgfm
54 from cmarkgfm.cmark import Options as cmarkgfmOptions
55
56 options = (
57 cmarkgfmOptions.CMARK_OPT_GITHUB_PRE_LANG
58 | cmarkgfmOptions.CMARK_OPT_SMART
59 )
60 html = cmarkgfm.markdown_to_html(markdown_text, options)
61
62The options are:
63
64+-----------------------------------------+----------------------------------------------------+
65| Option | Effect |
66+=========================================+====================================================+
67| CMARK_OPT_UNSAFE (>=0.5.0) | Allows rendering unsafe HTML and links. |
68+-----------------------------------------+----------------------------------------------------+
69| CMARK_OPT_SAFE (<0.5.0) | Prevents rendering unsafe HTML and links. |
70+-----------------------------------------+----------------------------------------------------+
71| CMARK_OPT_SMART | Render curly quotes, en/em-dashes, ellipses |
72+-----------------------------------------+----------------------------------------------------+
73| CMARK_OPT_NORMALIZE | Consolidate adjacent text nodes. |
74+-----------------------------------------+----------------------------------------------------+
75| CMARK_OPT_HARDBREAKS | Renders line breaks within paragraphs as ``<br>`` |
76+-----------------------------------------+----------------------------------------------------+
77| CMARK_OPT_NOBREAKS | Render soft line breaks as spaces. |
78+-----------------------------------------+----------------------------------------------------+
79| CMARK_OPT_SOURCEPOS | Adds ``data-sourcepos`` to HTML tags indicating |
80| | the corresponding line/col ranges in the input |
81+-----------------------------------------+----------------------------------------------------+
82| CMARK_OPT_FOOTNOTES | Parse footnotes. |
83+-----------------------------------------+----------------------------------------------------+
84| CMARK_OPT_VALIDATE_UTF8 | Validate UTF\-8 in the input before parsing, |
85| | replacing illegal sequenceswith the replacement |
86| | character U+FFFD. |
87+-----------------------------------------+----------------------------------------------------+
88| CMARK_OPT_GITHUB_PRE_LANG | Use GitHub\-style tags for code blocks. |
89+-----------------------------------------+----------------------------------------------------+
90| CMARK_OPT_LIBERAL_HTML_TAG | Be liberal in interpreting inline HTML tags. |
91+-----------------------------------------+----------------------------------------------------+
92| CMARK_OPT_STRIKETHROUGH_DOUBLE_TILDE | Only parse strikethroughs if surrounded by exactly |
93| | 2 tildes. Gives some compatibility with redcarpet. |
94+-----------------------------------------+----------------------------------------------------+
95| CMARK_OPT_TABLE_PREFER_STYLE_ATTRIBUTES | Use style attributes to align table cells instead |
96| | of align attributes. |
97+-----------------------------------------+----------------------------------------------------+
98
99
100**Unsafe rendering**
101
102Since version 0.5.0, the default behavior is safe. In earlier versions, the default behavior is unsafe, as described below. To render potentially unsafe HTML since 0.5.0 pass the ``CMARK_OPT_UNSAFE`` option.
103
104CommonMark can render potentially unsafe HTML, including raw HTML, raw Javascript, and potentially unsafe links (including links that run scripts). Although ``github_flavored_markdown_to_html`` prevents some raw HTML tags (including ``script``) from being rendered, it does not block unsafe URLs in links.
105
106Therefore it is recommend to call the rendering method with the SAFE option turned on. The safe option does not render raw HTML or potentially dangerous URLs. (Raw HTML is replaced by a placeholder comment; potentially dangerous URLs are replaced by empty strings.) Dangerous URLs are those that begin with ``javascript:``, ``vbscript:``, ``file:``, or ``data:`` (except for ``image/png``, ``image/gif``, ``image/jpeg``, or ``image/webp`` mime types) To do this, use:
107
108.. code-block:: python
109
110 # cmarkgfm<0.5.0
111 import cmarkgfm
112 from cmarkgfm.cmark import Options as cmarkgfmOptions
113
114 html = cmarkgfm.markdown_to_html(markdown_text, options=cmarkgfmOptions.CMARK_OPT_SAFE)
115 # or
116 html = cmarkgfm.github_flavored_markdown_to_html(markdown_text, options=cmarkgfmOptions.CMARK_OPT_SAFE)
117
118If you trust the markdown text to not include any unsafe tags and links, then you may skip this.
119
120
121Contributing
122------------
123
124Pull requests are welcome. :)
125
126
127License
128-------
129
130This project is under the MIT License. It includes components under differing
131copyright under the ``third_party`` directory in this source tree.
132