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):

from mdx_urlize import UrlizeExtension
import markdown
import pathlib
def docs(request):
    content = (pathlib.Path(__file__).parent / "docs.md").read_text()
    md = markdown.Markdown(
        extensions=["toc", "fenced_code", UrlizeExtension()], output_format="html5"
    )
    html = md.convert(content)
    return render(
        request,
        "docs.html",
        {
            "content": html,
            "toc": md.toc,
        },
    )

And in the docs.html template:

{% extends "base.html" %}
{% block title %}Documentation{% endblock %}
{% block content %}
<h1>Documentation</h1>
{{ toc|safe }}
{{ content|safe }}
{% endblock %}

Related

• jinja Custom Jinja template tags with attributes - 2023-07-01
• datasette Syntax highlighted code examples in Datasette - 2023-07-01
• markdown Rendering Markdown with the GitHub Markdown API - 2020-08-22
• django Building a blog in Django - 2023-08-15
• readthedocs Using custom Sphinx templates on Read the Docs - 2020-12-07
• github Syntax highlighting Python console examples with GFM - 2021-01-18
• sphinx Adding Sphinx autodoc to a project, and configuring Read The Docs to build it - 2021-08-10
• datasette Redirects for Datasette - 2020-11-25
• python Defining setup.py dependencies using a URL - 2022-08-13
• sphinx Using sphinx.ext.extlinks for issue links - 2021-02-17

Created 2021-04-03T21:22:12-07:00 · Edit