pycmarkgfm
Lightweight Python bindings to GitHub Flavored Markdown (GFM) library, cmark-gfm,
with enhanced support for task lists.
Features
- By design, rendering is compliant with GitHub's, since this package wraps GitHub's own C parser and serializer.
- As opposed to most cmark-gfm bindings out there, this package supports
parsing and toggling task lists.
- Compatibility:
with Python 3.7 & newer, on Linux, MacOS and Windows.
Installation
This packages is available on PyPi along with precompiled wheels for most architectures.
$ pip install pycmarkgfm
Usage
import pycmarkgfm
html = pycmarkgfm.markdown_to_html("Hello *world*")
html = pycmarkgfm.gfm_to_html("Hello ~world~")
Options
cmark and cmark-gfm come with a bunch of customization options (also known as flags) which are made available through
the pycmarkgfm.options
module. To use one or multiple options, use the options=
argument
with a mask (bitwise-or combination) of pycmarkgfm.options
. Each option is documented.
text = "hello\n<img src='doge.png'>"
print(pycmarkgfm.markdown_to_html(text))
from pycmarkgfm import options
print(pycmarkgfm.markdown_to_html(text, options=options.unsafe | options.hardbreaks))
Dealing with task lists
One of the distinctive features of this package is support for task lists.
You can get the list of tasks with their checked state, and update that state before rendering:
import pycmarkgfm
md = """
- [ ] eggs
- [x] milk
"""
with pycmarkgfm.parse_gfm(md) as document:
eggs, milk = document.get_tasks()
assert not eggs.checked
assert milk.checked
eggs.checked = True
print(document.to_commonmark())
There is a convenience method to easily toggle a task state from the rendered HTML. The typical use-case is that your
database stores the source GFM, renders it to HTML with gfm_to_html()
, then you have some client Javascript snippet
that is invoked when a checkbox is clicked. Thanks to the unique data-gfm-task
HTML attribute, you can update the
source GFM on the server:
import pycmarkgfm
md = """
- [ ] eggs
- [x] milk
"""
print(pycmarkgfm.gfm_to_html(md))
new_md = pycmarkgfm.gfm_toggle_task_by_id(md, "2:1-2:10", checked=pycmarkgfm.TOGGLE)
print(new_md)
You can also use checked=True/False
instead of TOGGLE
to force a particular state.
How is this package different from cmarkgfm
?
cmarkgfm is similar to this package, in fact cmarkgfm's cffi build script
is partially re-used in this project – in compliance with its MIT license.
As of October 2023, cmarkgfm is still a well-maintained project and I recommend using it if you don't need the extra
features provided by pycmarkgfm, most notably the support for task lists.
License
GNU GPLv3.
The project includes components under a different copyright under the third_party directory.