django-docutils 0.30.0

Docutils (a.k.a. reStructuredText, reST, RST) support for django.

django-docutils ·

docutils (a.k.a. reStructuredText / rst / reST) support for Django.

Documentation: https://django-docutils.git-pull.com/

django-docutils turns off docutils features that are risky on the web — raw HTML pass-through, file inclusion, and local docutils.conf lookup — and filters unsafe link schemes from rendered output. That reduces risk; it does not make untrusted markup safe. If people can submit their own reStructuredText or Markdown to your site (comments, profiles, CMS fields), read the Security topic first.

Quickstart

Install django-docutils:

$ pip install django-docutils

Next, add django_docutils to your INSTALLED_APPS in your settings file:

INSTALLED_APPS = [
    # ... your default apps,
    'django_docutils'
]

Template tag

In your template:

{% load django_docutils %}
{% rst %}
Welcome
=======

Write `reStructuredText <https://docutils.sourceforge.io/rst.html>`_ with
links, **bold** text, and highlighted code:

.. code-block:: python

   print("hello")
{% endrst %}

Template filter

In your template:

{% load django_docutils %}
{% filter rst %}
Welcome
=======

Write `reStructuredText <https://docutils.sourceforge.io/rst.html>`_ with
links, **bold** text, and highlighted code:

.. code-block:: python

   print("hello")
{% endfilter %}

Template engine (class-based view)

You can also use a class-based view to render reStructuredText (reST).

If you want to use reStructuredText as a django template engine, INSTALLED_APPS isn't required, instead you add this to your TEMPLATES variable in your settings:

TEMPLATES = [
    # ... Other engines
    {
        "NAME": "docutils",
        "BACKEND": "django_docutils.template.DocutilsTemplates",
        "DIRS": [],
        "APP_DIRS": True,
    }
]

Now django will be able to scan for .rst files and process them. In your view:

from django_docutils.views import DocutilsView

class HomeView(DocutilsView):
    template_name = 'base.html'
    rst_name = 'home.rst'

Settings

# Optional, automatically maps roles, directives and transformers
DJANGO_DOCUTILS_LIB_RST = {
    "docutils": {
        "strip_comments": True,
        "initial_header_level": 2,
    },
    "roles": {
        "local": {
            "gh": "django_docutils.lib.roles.github.github_role",
            "twitter": "django_docutils.lib.roles.twitter.twitter_role",
            "email": "django_docutils.lib.roles.email.email_role",
        }
    },
    "directives": {
        "code-block": "django_docutils.lib.directives.code.CodeBlock",
    }
}

# Optional
DJANGO_DOCUTILS_LIB_TEXT = {
    "uncapitalized_word_filters": ["project.my_module.my_capitalization_fn"]
}

For trusted static RST only — never for user-submitted content — docutils features that the default rendering disables can be re-enabled with an explicit opt-in (Security topic, docutils security guide):

DJANGO_DOCUTILS_LIB_RST = {
    "allow_unsafe_docutils_settings": True,
    "docutils": {
        "raw_enabled": True,
        "file_insertion_enabled": True,
    },
}

More information

• Python 3.10+
• Django 4.2+
• Documentation · Quickstart · Security · FAQ
• New to the ecosystem? What is docutils? untangles docutils, reStructuredText, Sphinx, and Markdown.
• reStructuredText primer and quick reference from the docutils project.