Useful Markdown extensions in Python#

I wanted to render some markdown in Python but with the following extra features:

URLize any bare URLs in the content, like GFM
Handle ```python at the start of a block without showing the python bit (even if no syntax highlight is applied)
Show a table of contents

For URLizing the best solution I’ve found is r0wb0t/markdown-urlize - it’s not available on PyPI so you have to download the mdx_urlize.py file and import from it.

The other two features can be handled by the toc and fenced_code extensions, both of which are included with Python Markdown and can be activated by passing their names as strings to the extensions= list.

Here’s what I ended up doing (in a Django view):

1
from mdx_urlize import UrlizeExtension
2
import markdown
3
import pathlib
4

5
def docs(request):
6
    content = (pathlib.Path(__file__).parent / "docs.md").read_text()
7
    md = markdown.Markdown(
8
        extensions=["toc", "fenced_code", UrlizeExtension()], output_format="html5"
9
    )
10
    html = md.convert(content)
11
    return render(
12
        request,
13
        "docs.html",
14
        {
15
            "content": html,
16
            "toc": md.toc,
17
        },
18
    )

And in the docs.html template:

1
{% extends "base.html" %}
2

3
{% block title %}Documentation{% endblock %}
4

5
{% block content %}
6
<h1>Documentation</h1>
7
{{ toc|safe }}
8
{{ content|safe }}
9
{% endblock %}