=====================
django.contrib.markup
=====================

.. module:: django.contrib.markup
   :synopsis: A collection of template filters that implement common markup languages.

Django provides template filters that implement the following markup
languages:

* ``textile`` -- implements `Textile`_ -- requires `PyTextile`_
* ``markdown`` -- implements `Markdown`_ -- requires `Python-markdown`_ (>=2.1)
* ``restructuredtext`` -- implements `reST (reStructured Text)`_
  -- requires `doc-utils`_

In each case, the filter expects formatted markup as a string and
returns a string representing the marked-up text. For example, the
``textile`` filter converts text that is marked-up in Textile format
to HTML.

To activate these filters, add ``'django.contrib.markup'`` to your
:setting:`INSTALLED_APPS` setting. Once you've done that, use
``{% load markup %}`` in a template, and you'll have access to these filters.
For more documentation, read the source code in
:file:`django/contrib/markup/templatetags/markup.py`.

.. warning::

    The output of markup filters is marked "safe" and will not be escaped when
    rendered in a template. Always be careful to sanitize your inputs and make
    sure you are not leaving yourself vulnerable to cross-site scripting or
    other types of attacks.

.. _Textile: http://en.wikipedia.org/wiki/Textile_%28markup_language%29
.. _Markdown: http://en.wikipedia.org/wiki/Markdown
.. _reST (reStructured Text): http://en.wikipedia.org/wiki/ReStructuredText
.. _PyTextile: http://loopcore.com/python-textile/
.. _Python-markdown: http://pypi.python.org/pypi/Markdown
.. _doc-utils: http://docutils.sf.net/

reStructured Text
-----------------

When using the ``restructuredtext`` markup filter you can define a
:setting:`RESTRUCTUREDTEXT_FILTER_SETTINGS` in your django settings to
override the default writer settings. See the `restructuredtext writer
settings`_ for details on what these settings are.

.. _restructuredtext writer settings: http://docutils.sourceforge.net/docs/user/config.html#html4css1-writer

Markdown
--------

The Python Markdown library supports options named "safe_mode" and
"enable_attributes". Both relate to the security of the output. To enable both
options in tandem, the markdown filter supports the "safe" argument::

    {{ markdown_content_var|markdown:"safe" }}

.. warning::

    Versions of the Python-Markdown library prior to 2.1 do not support the
    optional disabling of attributes. This is a security flaw. Therefore,
    ``django.contrib.markup`` has dropped support for versions of
    Python-Markdown < 2.1 in Django 1.5.