py-gfm documentation

Build status Coverage status Documentation status

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.


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:

Le me introduce you to [task lists](

- [ ] eggs
- [x] milk

You can also have fenced code blocks:

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(),

Supported features

  • Fenced code blocks
  • Literal line breaks
  • Tables
  • Hyperlink parsing (http, https, ftp, email and www 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.

Indices and tables