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.

# Installation

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

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.

# Usage

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

# Settings

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

"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

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 (16.7 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page