skip to navigation
skip to content

Not Logged In

django-markdown-deux 1.0.5

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

A small Django app that provides template tags for using
[Markdown]http://daringfireball.net/projects/markdown/ using the
[python-markdown2]https://github.com/trentm/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!]http://github.com/svetlyak40wt/django-markdown2 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"]https://github.com/trentm/python-markdown2/wiki/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]http://www.activestate.com/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://github.com/trentm/django-markdown-deux.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 setup.py install # or 'export PYTHONPATH=`pwd`/lib:$PYTHONPATH'

You'll also need the [python-markdown2
library]https://github.com/trentm/python-markdown2):

git clone git@github.com:trentm/python-markdown2.git
cd python-markdown2
python setup.py install # or 'export PYTHONPATH=`pwd`/python-markdown2/lib'


# Django project setup

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

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**
[Markdown]http://daringfireball.net/projects/markdown/
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/forms.py
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.
"
+ markdown_allowed()),
required=True)


## `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.

## `MARKDOWN_DEUX_STYLES` setting

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:

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

I.e. only the "default" style is defined and it just uses the [code-friendly
extra]https://github.com/trentm/python-markdown2/wiki/code-friendly 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:

# settings.py
from markdown_deux.conf.settings import MARKDOWN_DEUX_DEFAULT_STYLE

MARKDOWN_DEUX_STYLES = {
"default": 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 http://code.activestate.com/recipes/ 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),
r"http://code.activestate.com/recipes/\1/"),
],
"extras": {
"code-friendly": None,
"pyshell": None,
"demote-headers": 3,
"link-patterns": None,
# `class` attribute put on `pre` tags to enable using
# <http: code.google.com="" p="" google-code-prettify=""/> for syntax
# highlighting.
"html-classes": {"pre": "prettyprint"},
"cuddled-lists": None,
"footnotes": None,
"header-ids": None,
},
"safe_mode": "escape",
}
}


## `MARKDOWN_DEUX_HELP_URL` setting

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 <http: daringfireball.net="" projects="" markdown="" syntax="">, 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]http://code.activestate.com) uses:

MARKDOWN_DEUX_HELP_URL = "/help/markdown/"

To link to [its own Markdown syntax notes
URL]http://code.activestate.com/help/markdown/)  
File Type Py Version Uploaded on Size
django-markdown-deux-1.0.5.zip (md5) Source 2014-09-28 16KB
  • Downloads (All Versions):
  • 94 downloads in the last day
  • 590 downloads in the last week
  • 2797 downloads in the last month