Skip to main content

a Django app that provides template tags for using Markdown (using the python-markdown2 processor)

Project description

A small Django app that provides template tags for using Markdown using the python-markdown2 library.

What's with the "deux" in the name?

The obvious name for this project is django-markdown2. However, there already is one! and name confusion doesn't help anybody. Plus, I took French immersion in school for 12 years: might as well put it to use.

So why another project then?

Because I wanted to do something slightly different. Django-markdown2's markdown filter takes "extras" as arguments -- with the one exception that "safe" is transformed to python-markdown2's safe_mode argument. This is handy for quick usage. My use case is more commonly: lots of markdown filter and block usage in my Django templates with the same set of python-markdown2 options.


Choose the one of the following that works best for you:

  • Install the latest release from PyPI:

      pip install django-markdown-deux

    or, if you use ActivePython:

      pypm install django-markdown-deux

    These should install the dependent python-markdown2 package.

  • Get a git clone of the source tree:

      git clone git://

    You might want a particular tag:

      cd django-markdown-deux
      git tag -l   # list available tags
      git checkout $tagname

    Then you'll need the "lib" subdir on your PYTHONPATH:

      python install # or 'export PYTHONPATH=`pwd`/lib:$PYTHONPATH'

    You'll also need the python-markdown2 library:

      git clone
      cd python-markdown2
      python install   # or 'export PYTHONPATH=`pwd`/python-markdown2/lib'

Django project setup

  1. Add markdown_deux to INSTALLED_APPS in your project's "".

  2. Optionally set some of the MARKDOWN_DEUX_* settings. See the "Settings" section below.


The markdown_deux facilities typically take an optional "style" argument. This is a name for a set of options to the python-markdown2 processor. There is a "default" style that is used if no argument is given. See the MARKDOWN_DEUX_STYLES setting below for more.

markdown template filter

{% load markdown_deux_tags %}
{{ myvar|markdown:"STYLE" }}      {# convert `myvar` to HTML using the "STYLE" style #}
{{ myvar|markdown }}              {# same as `{{ myvar|markdown:"default"}}` #}

markdown template block tag

{% load markdown_deux_tags %}
{% markdown STYLE %}        {# can omit "STYLE" to use the "default" style #}
This is some **cool**
text here.
{% endmarkdown %}

markdown_allowed template tag

In a template:

{% markdown_allowed %}

will emit a short HTML blurb that says Markdown syntax is allowed. This can be handy for placing under form elements that accept markdown syntax. You can also use it as the help_text for a form field something like:

# myapp/
from markdown_deux.templatetags.markdown_deux_tags import markdown_allowed
class MyForm(forms.Form):
    description = forms.CharField(
        label="Description (required)",
        widget=forms.Textarea(attrs={"rows": 5}),
        help_text=_secondary_span("A brief description of your thing.<br/> "
            + markdown_allowed()),

markdown_cheatsheet tag

{% markdown_cheatsheet %}

This outputs HTML giving a narrow (appropriate for, e.g., a sidebar) listing of some of the more common Markdown features.

markdown_deux.markdown(TEXT, STYLE) in your Python code

The markdown filter and block tags above ultimately use this markdown_deux.markdown(...) function. You might find it useful to do Markdown processing in your Python code (e.g. in a view, in a model .save() method).


All settings for this app are optional.


A mapping of style name to a dict of keyword arguments for python-markdown2's markdown2.markdown(text, **kwargs). For example the default setting is effectively:

    "default": {
        "extras": {
            "code-friendly": None,
        "safe_mode": "escape",

I.e. only the "default" style is defined and it just uses the code-friendly extra and escapes raw HTML in the given Markdown (for safety).

Here is how you might add styles of your own, and preserve the default style:

from markdown_deux.conf.settings import MARKDOWN_DEUX_DEFAULT_STYLE

    "trusted": {
        "extras": {
            "code-friendly": None,
        # Allow raw HTML (WARNING: don't use this for user-generated
        # Markdown for your site!).
        "safe_mode": False,
    # Here is what currently uses.
    "recipe": {
        "extras": {
            "code-friendly": None,
        "safe_mode": "escape",
        "link_patterns": [
            # Transform "Recipe 123" in a link.
            (re.compile(r"recipe\s+#?(\d+)\b", re.I),
        "extras": {
            "code-friendly": None,
            "pyshell": None,
            "demote-headers": 3,
            "link-patterns": None,
            # `class` attribute put on `pre` tags to enable using
            # <> for syntax
            # highlighting.
            "html-classes": {"pre": "prettyprint"},
            "cuddled-lists": None,
            "footnotes": None,
            "header-ids": None,
        "safe_mode": "escape",


A URL for to which to link for full markdown syntax default. This link is only in the output of the markdown_allowed and markdown_cheatsheet template tags.

The default is, the canonical Markdown syntax reference. However, if your site uses Markdown with specific tweaks, you may prefer to have your own override. For example, ActiveState Code uses:

MARKDOWN_DEUX_HELP_URL = "/help/markdown/"

To link to its own Markdown syntax notes URL.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution (18.2 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page