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.<br/> "
+ 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/).
Raw data
{
"_id": null,
"home_page": "http://github.com/trentm/django-markdown-deux",
"name": "django-markdown-deux",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "django markdown markdown2 text markup html",
"author": "Trent Mick",
"author_email": "trentm@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/80/a5/d61ee6fc26cbb0d737986ed23e13309c88f2ae7f1fcdf2460a525323a3ed/django-markdown-deux-1.0.5.zip",
"platform": "UNKNOWN",
"description": "A small Django app that provides template tags for using\n[Markdown](http://daringfireball.net/projects/markdown/) using the\n[python-markdown2](https://github.com/trentm/python-markdown2) library.\n\n# What's with the \"deux\" in the name?\n\nThe obvious name for this project is `django-markdown2`. However, there\n[already is one!](http://github.com/svetlyak40wt/django-markdown2) and name\nconfusion doesn't help anybody. Plus, I took French immersion in school for 12\nyears: might as well put it to use.\n\n# So why another project then?\n\nBecause I wanted to do something slightly different. Django-markdown2's\n`markdown` filter takes\n[\"extras\"](https://github.com/trentm/python-markdown2/wiki/Extras) as arguments\n-- with the one exception that \"safe\" is transformed to python-markdown2's\n`safe_mode` argument. This is handy for quick usage. My use case is more\ncommonly: lots of `markdown` filter and block usage in my Django templates with\nthe same set of python-markdown2 options.\n\n\n# Installation\n\nChoose the *one* of the following that works best for you:\n\n- Install the latest release from PyPI:\n\n pip install django-markdown-deux\n\n or, if you use [ActivePython](http://www.activestate.com/activepython):\n\n pypm install django-markdown-deux\n\n These should install the dependent `python-markdown2` package.\n\n- Get a git clone of the source tree:\n\n git clone git://github.com/trentm/django-markdown-deux.git\n\n You might want a particular tag:\n\n cd django-markdown-deux\n git tag -l # list available tags\n git checkout $tagname\n\n Then you'll need the \"lib\" subdir on your PYTHONPATH:\n\n python setup.py install # or 'export PYTHONPATH=`pwd`/lib:$PYTHONPATH'\n\n You'll also need the [python-markdown2\n library](https://github.com/trentm/python-markdown2):\n\n git clone git@github.com:trentm/python-markdown2.git\n cd python-markdown2\n python setup.py install # or 'export PYTHONPATH=`pwd`/python-markdown2/lib'\n\n\n# Django project setup\n\n1. Add `markdown_deux` to `INSTALLED_APPS` in your project's \"settings.py\".\n\n2. Optionally set some of the `MARKDOWN_DEUX_*` settings. See the \"Settings\"\n section below.\n\n\n# Usage\n\nThe `markdown_deux` facilities typically take an optional \"style\" argument. This\nis a name for a set of options to the `python-markdown2` processor. There is\na \"default\" style that is used if no argument is given. See the\n`MARKDOWN_DEUX_STYLES` setting below for more.\n\n## `markdown` template filter\n\n {% load markdown_deux_tags %}\n ...\n {{ myvar|markdown:\"STYLE\" }} {# convert `myvar` to HTML using the \"STYLE\" style #}\n {{ myvar|markdown }} {# same as `{{ myvar|markdown:\"default\"}}` #}\n\n## `markdown` template block tag\n\n {% load markdown_deux_tags %}\n ...\n {% markdown STYLE %} {# can omit \"STYLE\" to use the \"default\" style #}\n This is some **cool**\n [Markdown](http://daringfireball.net/projects/markdown/)\n text here.\n {% endmarkdown %}\n\n## `markdown_allowed` template tag\n\nIn a template:\n\n {% markdown_allowed %}\n\nwill emit a short HTML blurb that says Markdown syntax is allowed. This can be\nhandy for placing under form elements that accept markdown syntax. You can also\nuse it as the `help_text` for a form field something like:\n\n # myapp/forms.py\n from markdown_deux.templatetags.markdown_deux_tags import markdown_allowed\n class MyForm(forms.Form):\n #...\n description = forms.CharField(\n label=\"Description (required)\",\n widget=forms.Textarea(attrs={\"rows\": 5}),\n help_text=_secondary_span(\"A brief description of your thing.<br/> \"\n + markdown_allowed()),\n required=True)\n\n\n## `markdown_cheatsheet` tag\n\n {% markdown_cheatsheet %}\n\nThis outputs HTML giving a narrow (appropriate for, e.g., a sidebar) listing of\nsome of the more common Markdown features.\n\n\n## `markdown_deux.markdown(TEXT, STYLE)` in your Python code\n\nThe `markdown` filter and block tags above ultimately use this\n`markdown_deux.markdown(...)` function. You might find it useful to do Markdown\nprocessing in your Python code (e.g. in a view, in a model `.save()` method).\n\n\n# Settings\n\nAll settings for this app are optional.\n\n## `MARKDOWN_DEUX_STYLES` setting\n\nA mapping of style name to a dict of keyword arguments for python-markdown2's\n`markdown2.markdown(text, **kwargs)`. For example the default setting is\neffectively:\n\n MARKDOWN_DEUX_STYLES = {\n \"default\": {\n \"extras\": {\n \"code-friendly\": None,\n },\n \"safe_mode\": \"escape\",\n },\n }\n\nI.e. only the \"default\" style is defined and it just uses the [code-friendly\nextra](https://github.com/trentm/python-markdown2/wiki/code-friendly) and escapes\nraw HTML in the given Markdown (for safety).\n\nHere is how you might add styles of your own, and preserve the default style:\n\n # settings.py\n from markdown_deux.conf.settings import MARKDOWN_DEUX_DEFAULT_STYLE\n\n MARKDOWN_DEUX_STYLES = {\n \"default\": MARKDOWN_DEUX_DEFAULT_STYLE,\n \"trusted\": {\n \"extras\": {\n \"code-friendly\": None,\n },\n # Allow raw HTML (WARNING: don't use this for user-generated\n # Markdown for your site!).\n \"safe_mode\": False,\n }\n # Here is what http://code.activestate.com/recipes/ currently uses.\n \"recipe\": {\n \"extras\": {\n \"code-friendly\": None,\n },\n \"safe_mode\": \"escape\",\n \"link_patterns\": [\n # Transform \"Recipe 123\" in a link.\n (re.compile(r\"recipe\\s+#?(\\d+)\\b\", re.I),\n r\"http://code.activestate.com/recipes/\\1/\"),\n ],\n \"extras\": {\n \"code-friendly\": None,\n \"pyshell\": None,\n \"demote-headers\": 3,\n \"link-patterns\": None,\n # `class` attribute put on `pre` tags to enable using\n # <http://code.google.com/p/google-code-prettify/> for syntax\n # highlighting.\n \"html-classes\": {\"pre\": \"prettyprint\"},\n \"cuddled-lists\": None,\n \"footnotes\": None,\n \"header-ids\": None,\n },\n \"safe_mode\": \"escape\",\n }\n }\n\n\n## `MARKDOWN_DEUX_HELP_URL` setting\n\nA URL for to which to link for full markdown syntax default. This link is\nonly in the output of the `markdown_allowed` and `markdown_cheatsheet`\ntemplate tags.\n\nThe default is <http://daringfireball.net/projects/markdown/syntax>, the\ncanonical Markdown syntax reference. However, if your site uses Markdown with\nspecific tweaks, you may prefer to have your own override. For example,\n[ActiveState Code](http://code.activestate.com) uses:\n\n MARKDOWN_DEUX_HELP_URL = \"/help/markdown/\"\n\nTo link to [its own Markdown syntax notes\nURL](http://code.activestate.com/help/markdown/).",
"bugtrack_url": null,
"license": "MIT",
"summary": "a Django app that provides template tags for using Markdown (using the python-markdown2 processor)",
"version": "1.0.5",
"split_keywords": [
"django",
"markdown",
"markdown2",
"text",
"markup",
"html"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "6e3016740f3164020ff93882bc7a6cf0",
"sha256": "5b4a3cd9454af5b4cec0e19151b41d98d09400ddae0688afb81dbf62a4edafff"
},
"downloads": -1,
"filename": "django-markdown-deux-1.0.5.zip",
"has_sig": false,
"md5_digest": "6e3016740f3164020ff93882bc7a6cf0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16727,
"upload_time": "2014-09-28T03:28:12",
"upload_time_iso_8601": "2014-09-28T03:28:12.205622Z",
"url": "https://files.pythonhosted.org/packages/80/a5/d61ee6fc26cbb0d737986ed23e13309c88f2ae7f1fcdf2460a525323a3ed/django-markdown-deux-1.0.5.zip",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2014-09-28 03:28:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "trentm",
"github_project": "django-markdown-deux",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "django-markdown-deux"
}
JSON
