Quickstart

Installation

Install the 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. Their versions use markers 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

  • uv:

    $ uv add django-docutils --prerelease allow

via trunk (can break easily):

  • pip:

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

  • uv:

    $ uv add "django-docutils @ 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 Django settings file:

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

Render your first block

Load the template tags and put a small reStructuredText document inside {% rst %}:

{% load django_docutils %}
{% rst %}
Hello
=====

Welcome to **reStructuredText** in Django.
{% endrst %}

Output:

<main id="hello">
<h1 class="title is-1">Hello</h1>
<p>Welcome to <strong>reStructuredText</strong> in Django.</p>
</main>

Next steps

Choose the entry point for your Django site:

  1. Template tag

  2. Class-based view

  3. Security

  4. Template filter for legacy templates that already use the deprecated filter

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