Using Markdown with Django

The Basics

Markdown support is already implemented in Django via the markup add-on. You simply need to make the markdown module available on the system and tell Django to use it.

Install markdown and make sure it is in your python path. Include 'django.contrib.markup' in INSTALLED_APPS in your settings.py file.

You will then need to load the markup module in a template:

{% load markup %}

After that, you should be able to use the markdown filter in that template by putting "|markdown" after a variable, e.g.:

{{ post.body|markdown }}

Advanced Options

To load extensions, list them in quotes separated by comas:

{{ post.body|markdown:"wikilink,footnotes" }}

If you want to disable HTML, include "safe" as the first argument:

{{ post.body|markdown:"safe" }}

Alternatively, you may prefer the more sophisticated approach available in the django-template-utils project.

Known Issues

• Extension and safe_mode support were only added to Django on Dec. 2, 2007. If you are using an earlier version of Django (including the official releases 0.90, 0.91, 0.95, and 0.96), please see below.

Adding Extension Support to Older Django Versions

Note: The code below is recommended for the Django official releases 0.90, 0.91, 0.95, and 0.96. If you are running a later version it is recommended that you use the more up-to-date code in Django tickets #2910 and #6387 which supports more recent changes to both Django and Python-Markdown. Ticket #2910 has since been committed in Django changeset [6834] (on Dec. 2, 2007) and ticket #6387 in changeset [7423] (on April 14, 2008) so Markdown's extension and unicode support are now fully built into Django itself. Therefore, if you are running Django trunk, you may ignore this section.

If you want to add extension and safe_mode support to older versions of Django (0.90, 0.91, 0.95, and 0.96), you will need to make some changes to the markdown template tag. It is recommended that you copy the contents of 'django/contrib/markup/' to a directory markup in your project or another appropriate location on your path. Then edit this localized copy of 'markup/templatetags/markup.py` replacing the definition of the markdown() function with the following:

def markdown(value, arg=''):

    try:
        import markdown
    except ImportError:
        if settings.DEBUG:
            raise (template.TemplateSyntaxError, 
                   "Error in {% markdown %} filter: " 
                   + "The markdown library isn't installed.")
        else :
            from django.utils.html import escape, linebreaks
            return linebreaks(escape(value))
    else:
        extensions=arg.split(",")
        if len(extensions) > 0 and extensions[0] == "safe" :
            extensions = extensions[1:]
            safe_mode = True
        else :
            safe_mode = False
        return markdown.markdown(value, extensions, safe_mode=safe_mode)

You will then need to change 'django.contrib.markup' to 'markup' in INSTALLED_APPS in your settings.py file. (You could just edit the file in django/contrib/markup/templatetags/markup.py directly, but your changes will likely be lost when upgrading and such a practice is not recommended by the Django team.)

You should then be able to load extensions as described above.