Docutils Front-End Tools
- Contact:
- docutils-develop@lists.sourceforge.net
- Revision:
- 10348
- Date:
- 2026-06-11
- Copyright:
- This document has been placed in the public domain.
Introduction
In addition to the generic "docutils" application, Docutils installs a set of small front ends, each specialized for a specific "Reader" (which knows how to interpret a file in context), "Parser" (which understands the syntax of the text), and "Writer" (which knows how to generate a specific data format).
Most [1] front-end tools have common options and the same command-line usage pattern:
toolname [options] [source]
See the tools below for concrete examples.
Each tool has a --help option which lists the command-line options and arguments it supports. Processing can also be customized with configuration files.
The postional argument, "source", is optional. If no argument is specified, the standard input (stdin) is used for the source.
Output is written to the standard output by default. An output file can be specified with redirection or the --output (or -o) option.
toolname [options] [source] > destination
Getting Help
First, try the "--help" option each front-end tool has.
Command line options and their corresponding configuration file entries are detailed in Docutils Configuration.
Users who have questions or need assistance with Docutils or reStructuredText should post a message to the Docutils-users mailing list.
The Tools
Generic Command Line Front End
docutils
- CLI name:
docutils
- Readers:
Standalone (default), PEP
- Parsers:
reStructuredText (default), Markdown (requires 3rd party packages)
- Writers:
html, html4css1, html5 (default), latex2e, manpage, odt, pep_html, pseudo-xml, s5_html, xelatex, xml,
- Config:
Since Docutils 0.19, you can start the generic front end like:
docutils test.rst --output test.html
Alternatively, use Python's -m option, or the docutils-cli.py script in the tools/ directory.
The generic front end allows combining "reader", "parser", and "writer" components from the Docutils package or 3rd party plug-ins.
For example, to process a Markdown file "test.md" into Pseudo-XML:
docutils --parser=markdown --writer=pseudoxml test.md > test.txt
Another example is converting a reStructuredText PEP source into a HTML preview [2]:
docutils --reader=pep --writer=pep_html pep-0287.rst -o pep-0287.html
The pep_html writer makes use of a "pep-html-template" file and the "pep.css" stylesheet (both in the docutils/writers/pep_html/ directory), but these can be overridden by command-line options or configuration files.
Use the "--help" option together with the component-selection options to get the correct list of supported command-line options. Example:
docutils --parser=markdown --writer=xml --help
HTML-Generating Tools
rst2html
- Reader:
Standalone
- Parser:
reStructuredText
- Writer:
rst2html is the front-end for the default Docutils HTML writer. The default writer may change with the development of HTML, browsers, Docutils, and the web. The current default is html4css1, it will change to html5 in Docutils 2.0.
rst2html4
- Reader:
Standalone
- Parser:
reStructuredText
- Writer:
The rst2html4 front end reads standalone reStructuredText source files and produces XHTML 1.0 Transitional output. A CSS stylesheet is required for proper rendering; a simple but complete stylesheet is installed and used by default (see Stylesheets below).
For example, to process a reStructuredText file "test.rst" into HTML:
rst2html test.rst -o test.html
Now open the "test.html" file in your favourite browser to see the results. To get a footer with a link to the source file, date & time of processing, and links to the Docutils project, add some options:
rst2html --source-link --time --generator test.rst -o test.html
Stylesheets
rst2html inserts into the generated HTML a cascading stylesheet (or a link to a stylesheet, when passing the "--link-stylesheet" option). A stylesheet is required for proper rendering. The default stylesheet (docutils/writers/html4css1/html4css1.css, located in the installation directory) is provided for basic use.
To use different stylesheet(s), specify the stylesheets' location(s) as comma-separated list with the "--stylesheet" or "--stylesheet-path" options. To experiment with styles, please see the guide to writing HTML (CSS) stylesheets for Docutils.
rst2html5
- Reader: