1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
Metadata-Version: 2.1
Name: cmarkgfm
Version: 2024.11.20
Summary: Minimal bindings to GitHub's fork of cmark
Home-page: https://github.com/theacodes/cmarkgfm
Author: The Python Packaging Authority
Author-email: me@thea.codes, pypa-dev@googlegroups.com
Project-URL: Bug Reports, https://github.com/theacodes/cmarkgfm/issues
Project-URL: Funding, https://donate.pypi.org
Project-URL: Source, https://github.com/theacodes/cmarkgfm
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Requires-Dist: cffi>=1.15.0
cmarkgfm - Python bindings to GitHub's cmark
============================================
Minimalist Python bindings to GitHub's fork of cmark.
Installation
------------
This package is published on PyPI as `cmarkgfm <https://pypi.org/project/cmarkgfm/>`__
and can be installed with `pip` or `pipenv`::
pip install --user cmarkgfm
pipenv install cmarkgfm
Wheels are provided for macOS, Linux, and Windows for Python 3.6, 3.7, 3.8, 3.9, 3.10 and 3.11.
Usage
-----
High-level usage is really straightforward. To render normal CommonMark
markdown:
.. code-block:: python
import cmarkgfm
html = cmarkgfm.markdown_to_html(markdown_text)
To render GitHub-flavored markdown:
.. code-block:: python
import cmarkgfm
html = cmarkgfm.github_flavored_markdown_to_html(markdown_text)
Advanced Usage
--------------
**Options**
Both rendering methods ``markdown_to_html`` and ``github_flavored_markdown_to_html`` have
an optional ``options`` argument that can be used to activate `options of cmark <https://manpages.debian.org/stretch/cmark/cmark.1.en.html>`_.
For example:
.. code-block:: python
import cmarkgfm
from cmarkgfm.cmark import Options as cmarkgfmOptions
options = (
cmarkgfmOptions.CMARK_OPT_GITHUB_PRE_LANG
| cmarkgfmOptions.CMARK_OPT_SMART
)
html = cmarkgfm.markdown_to_html(markdown_text, options)
The options are:
+-----------------------------------------+----------------------------------------------------+
| Option | Effect |
+=========================================+====================================================+
| CMARK_OPT_UNSAFE (>=0.5.0) | Allows rendering unsafe HTML and links. |
+-----------------------------------------+----------------------------------------------------+
| CMARK_OPT_SAFE (<0.5.0) | Prevents rendering unsafe HTML and links. |
+-----------------------------------------+----------------------------------------------------+
| CMARK_OPT_SMART | Render curly quotes, en/em-dashes, ellipses |
+-----------------------------------------+----------------------------------------------------+
| CMARK_OPT_NORMALIZE | Consolidate adjacent text nodes. |
+-----------------------------------------+----------------------------------------------------+
| CMARK_OPT_HARDBREAKS | Renders line breaks within paragraphs as ``<br>`` |
+-----------------------------------------+----------------------------------------------------+
| CMARK_OPT_NOBREAKS | Render soft line breaks as spaces. |
+-----------------------------------------+----------------------------------------------------+
| CMARK_OPT_SOURCEPOS | Adds ``data-sourcepos`` to HTML tags indicating |
| | the corresponding line/col ranges in the input |
+-----------------------------------------+----------------------------------------------------+
| CMARK_OPT_FOOTNOTES | Parse footnotes. |
+-----------------------------------------+----------------------------------------------------+
| CMARK_OPT_VALIDATE_UTF8 | Validate UTF\-8 in the input before parsing, |
| | replacing illegal sequenceswith the replacement |
| | character U+FFFD. |
+-----------------------------------------+----------------------------------------------------+
| CMARK_OPT_GITHUB_PRE_LANG | Use GitHub\-style tags for code blocks. |
+-----------------------------------------+----------------------------------------------------+
| CMARK_OPT_LIBERAL_HTML_TAG | Be liberal in interpreting inline HTML tags. |
+-----------------------------------------+----------------------------------------------------+
| CMARK_OPT_STRIKETHROUGH_DOUBLE_TILDE | Only parse strikethroughs if surrounded by exactly |
| | 2 tildes. Gives some compatibility with redcarpet. |
+-----------------------------------------+----------------------------------------------------+
| CMARK_OPT_TABLE_PREFER_STYLE_ATTRIBUTES | Use style attributes to align table cells instead |
| | of align attributes. |
+-----------------------------------------+----------------------------------------------------+
**Unsafe rendering**
Since 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.
CommonMark 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.
Therefore 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:
.. code-block:: python
# cmarkgfm<0.5.0
import cmarkgfm
from cmarkgfm.cmark import Options as cmarkgfmOptions
html = cmarkgfm.markdown_to_html(markdown_text, options=cmarkgfmOptions.CMARK_OPT_SAFE)
# or
html = cmarkgfm.github_flavored_markdown_to_html(markdown_text, options=cmarkgfmOptions.CMARK_OPT_SAFE)
If you trust the markdown text to not include any unsafe tags and links, then you may skip this.
Contributing
------------
Pull requests are welcome. :)
License
-------
This project is under the MIT License. It includes components under differing
copyright under the ``third_party`` directory in this source tree.
|
