Quickstart

Installation

For latest official version:

$ pip install django-docutils

Upgrading:

$ pip install --upgrade django-docutils

Developmental releases

New versions of django-docutils are published to PyPI as alpha, beta, or release candidates. In their versions you will see notification like a1, b1, and rc1, respectively. 1.10.0b4 would mean the 4th beta release of 1.10.0 before general availability.

  • pip:

    $ pip install --upgrade --pre django-docutils

  • pipx:

    $ pipx install --suffix=@next 'django-docutils' --pip-args '\--pre' --force
// Usage: django-docutils@next

  • uv:

    $ uv add django-docutils --prerelease allow

  • uvx:

    $ uvx --from 'django-docutils' --prerelease allow django-docutils

via trunk (can break easily):

  • pip:

    $ pip install -e git+https://github.com/tony/django-docutils.git#egg=django-docutils

  • pipx:

    $ pipx install --suffix=@master 'django-docutils @ git+https://github.com/tony/django-docutils.git@master' --force

  • uv:

    $ uv tool install django-docutils --from git+https://github.com/tony/django-docutils.git

New to reStructuredText?

reStructuredText is the markup language; docutils is the library that parses and renders it. The official primer and quick reference cover the syntax; What is docutils? maps the wider ecosystem (docutils, Sphinx, Markdown), and the FAQ answers common questions.

Add the django app

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

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

Next steps

Integrate docutils to your django site:

  1. Template tag

  2. Template filter

  3. Class-based view

  4. Security

The rendering defaults disable docutils features that are risky on the web; if your site accepts user-authored markup, start with Security.