What is docutils?

A field guide to the names you will meet when rendering markup in Django: docutils, reStructuredText, Sphinx, and friends — and where django-docutils fits among them.

What is reStructuredText?

reStructuredText (also written reST, RST, or rst) is a plaintext markup language, comparable to Markdown but older and more extensible. The fastest ways in are the official primer and the quick reference.

What is docutils?

docutils is the Python library that parses reStructuredText and publishes it to other formats. reStructuredText is the language; docutils is the processing system — the parser is one docutils component, the output writers are others. The docutils documentation covers both halves.

What is Sphinx — and is django-docutils Sphinx?

Sphinx is a documentation generator built on top of docutils: it adds cross-references, multi-page projects, themes, and extensions, and it renders sites like the Python documentation. Its reStructuredText primer is another good introduction.

django-docutils is not Sphinx. It renders RST fragments and pages inside Django templates and views:

Tool	Built on	Use it for
docutils	—	Parsing and rendering single documents
Sphinx	docutils	Documentation sites and books
MyST-Parser	docutils / Sphinx	Markdown in docutils and Sphinx
django-docutils	docutils + Django	RST inside Django templates and views

Can docutils parse Markdown?

Yes — since docutils 0.19, with a third-party parser installed: myst-docutils (recommended) or pycmark. docutils selects them through its markdown / commonmark parser aliases — see the docutils configuration reference. The older recommonmark wrapper is deprecated and will be removed in docutils 1.0.

django-docutils itself renders reStructuredText. To serve CommonMark Markdown in a docutils or Sphinx pipeline, reach for MyST-Parser.

What can docutils output?

reStructuredText input can leave docutils in many formats — django-docutils uses the HTML writer family, the rest come with the docutils CLI tools such as rst2html5, rst2latex, and rst2man:

Writer	Output
html5	HTML5
html4css1	XHTML 1.0 (the html default for now)
latex2e, xetex	LaTeX / XeTeX, typically en route to PDF
manpage	Unix man pages
odf_odt	OpenDocument text (LibreOffice)
s5_html	S5 HTML slideshows
docutils_xml, pseudoxml	Document-tree XML / debugging output

Where does django-docutils fit?

Your template or view hands RST source to django-docutils — via Template tag, Template filter, or Class-based view — which runs the docutils parser with hardened settings, removes raw nodes and unsafe link targets from the document tree, and returns HTML produced by docutils’ HTML writers.

Rendering user-authored markup carries risk that configuration can reduce, not remove — see Security and docutils’ own security guide.