py-gfm documentation¶
This is an implementation of GitHub-Flavored Markdown written as an extension to the Python Markdown library. It aims for maximal compatibility with GitHub’s rendering.
py-gfm code is under a BSD-style license.
Installation¶
pip install py-gfm
Quick start¶
All-in-one extension¶
import markdown
from mdx_gfm import GithubFlavoredMarkdownExtension
source = """
Hello, *world*! This is a ~~good~~marvelous day!
Here is an auto link: https://example.org/
Le me introduce you to [task lists](https://github.com/blog/1375-task-lists-in-gfm-issues-pulls-comments):
- [ ] eggs
- [x] milk
You can also have fenced code blocks:
```python
import this
```
"""
# Direct conversion:
html = markdown.markdown(
source, extensions=[GithubFlavoredMarkdownExtension()])
# Factory-like:
md = markdown.Markdown(extensions=[GithubFlavoredMarkdownExtension()])
html = md.convert(source)
# By module name (not recommended if you need custom configs):
html = markdown.markdown(source, extensions=['mdx_gfm'])
À la carte¶
import markdown
from gfm import AutolinkExtension, TaskListExtension
html = markdown.markdown(
source, extensions=[AutolinkExtension(),
TaskListExtension(max_depth=2)])
Available extensions¶
Modules¶
Supported features¶
- Fenced code blocks
- Literal line breaks
- Tables
- Hyperlink parsing (
http
,https
,ftp
,email
andwww
subdomains) - Code highlighting for code blocks if Pygments is available
- Mixed-style lists with no separation
- Strikethrough
- Task lists
Unsupported features¶
This implementation does not support all of GFM features and has known differences in how rendering is done.
- By design, link to commits, issues, pull requests and user profiles are not supported since this is application specific. Feel free to subclass the provided classes to implement your own logic.
- There is no emoji support.
- There is no horizontal rule (
---
ie.<hr>
) support. - Nested lists are not behaving exactly like GitHub’s: issue #10.
- Contrary to GitHub, only double-tilde’d text renders strikethrough, not single-tile’d: issue #14.