https://github.com/martin005/comrak-ext
Extended Python bindings for the Comrak Rust library, a fast CommonMark/GFM parser
https://github.com/martin005/comrak-ext
Last synced: 6 months ago
JSON representation
Extended Python bindings for the Comrak Rust library, a fast CommonMark/GFM parser
- Host: GitHub
- URL: https://github.com/martin005/comrak-ext
- Owner: Martin005
- License: other
- Created: 2025-09-04T11:06:07.000Z (11 months ago)
- Default Branch: master
- Last Pushed: 2026-01-19T18:22:54.000Z (6 months ago)
- Last Synced: 2026-01-20T00:46:51.900Z (6 months ago)
- Language: Rust
- Homepage: https://pypi.org/project/comrak-ext/
- Size: 161 KB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# comrak-ext
[](https://github.com/astral-sh/uv)
[](https://pdm.fming.dev)
[](https://pypi.org/project/comrak-ext)
[](https://pypi.org/project/comrak-ext)
[](https://pypi.python.org/pypi/comrak-ext)
[](https://results.pre-commit.ci/latest/github/Martin005/comrak-ext/master)
Extended Python bindings for the Comrak Rust library, a fast CommonMark/GFM parser. Fork of [lmmx/comrak](https://github.com/lmmx/comrak).
## Installation
```bash
pip install comrak-ext
```
### Requirements
- Python 3.9+
## Features
Fast Markdown to HTML parser in Rust, shipped for Python via PyO3.
## API
### `markdown_to_html`
Render Markdown to HTML:
```python
from comrak import ExtensionOptions, markdown_to_html
extension_options = ExtensionOptions()
markdown_to_html("foo :smile:", extension_options)
# '
foo :smile:
\n'
extension_options.shortcodes = True
markdown_to_html("foo :smile:", extension_options)
# '
foo 😄
\n'
```
### `markdown_to_commonmark`
Render Markdown to CommonMark:
```python
from comrak import RenderOptions, ListStyleType, markdown_to_commonmark
render_options = RenderOptions()
markdown_to_commonmark("- one\n- two\n- three", render_options=render_options)
# '- one\n- two\n- three\n' – default is Dash
render_options.list_style = ListStyleType.Plus
markdown_to_commonmark("- one\n- two\n- three", render_options=render_options)
# '+ one\n+ two\n+ three\n'
```
### `markdown_to_xml`
Render Markdown to XML:
```python
from comrak import RenderOptions, markdown_to_xml
render_options = RenderOptions(sourcepos=True)
markdown_to_xml("Hello, **Markdown**!", render_options=render_options)
# '\n\n\n \n Hello, \n \n Markdown\n \n !\n \n\n'
```
### `parse_document`
Parse Markdown into an abstract syntax tree (AST):
```python
from comrak import ExtensionOptions, Document, Text, Paragraph, parse_document
extension_options = ExtensionOptions(front_matter_delimiter = "---")
md_content = """---
This is a text in FrontMatter
---
Hello, Markdown!
"""
x = parse_document(md_content, extension_options)
assert isinstance(x.node_value, Document)
assert not hasattr(x.node_value, "value")
assert len(x.children) == 2
assert isinstance(x.children[0].node_value, FrontMatter)
assert isinstance(x.children[0].node_value.value, str)
assert x.children[0].node_value.value.strip() == "---\nThis is a text in FrontMatter\n---"
assert isinstance(x.children[1].node_value, Paragraph)
assert len(x.children[1].children) == 1
assert isinstance(x.children[1].children[0].node_value, Text)
assert isinstance(x.children[1].children[0].node_value.value, str)
assert x.children[1].children[0].node_value.value == "Hello, Markdown!"
```
### `format_html`
Format an AST back to HTML:
```python
from comrak import parse_document, format_html
p = parse_document("> Greentext blockquote requires a space after `>`")
format_html(p)
# '
\nGreentext blockquote requires a space after >
\n
\n'
```
### `format_commonmark`
Format an AST back to CommonMark:
```python
from comrak import parse_document, format_commonmark
p = parse_document("> Greentext blockquote requires a space after `>`")
format_commonmark(p)
# '> Greentext blockquote requires a space after `>`\n'
```
### `format_xml`
Format an AST back to XML:
```python
from comrak import parse_document, format_xml
p = parse_document("> Greentext blockquote requires a space after `>`")
format_xml(p)
# '\n\n\n \n \n Greentext blockquote requires a space after \n >\n \n \n\n'
```
### Options
All options are exposed in a simple manner and can be used with all functions.
Refer to the [Comrak docs](https://docs.rs/comrak/latest/comrak/struct.Options.html) for all available options.
## Benchmarks
Tested with small (8 lines) and medium (1200 lines) markdown strings
- vs. [markdown](https://pypi.org/project/markdown): 15x faster (S/M)
- vs. [markdown2](https://pypi.org/project/markdown2): 20x (S) - 60x (M) faster
## Contributing
Maintained by [Martin005](https://github.com/Martin005). Contributions welcome!
1. **Issues & Discussions**: Please open a GitHub issue or discussion for bugs, feature requests, or questions.
2. **Pull Requests**: PRs are welcome!
- Install the dev extra (e.g. with [uv](https://docs.astral.sh/uv/): `uv pip install -e .[dev]`)
- Run tests (when available) and include updates to docs or examples if relevant.
- If reporting a bug, please include the version and the error message/traceback if available.
## License
Licensed under the 2-Clause BSD License. See [LICENSE](https://github.com/Martin005/comrak-ext/blob/master/LICENSE) for all the details.