Docutils Configuration

Settings priority

Configuration file settings override the built-in defaults, and command-line options override all. Some settings override also an associated setting; [11] others append values from the various sources. [12]

For the technicalities, see Docutils Runtime Settings.

Configuration Files

Configuration files are used for persistent customization; they can be set once and take effect every time you use a component, e.g., via a front-end tool.

By default, Docutils checks the following places for configuration files, in the following order:

1. /etc/docutils.conf: This is a system-wide configuration file, applicable to all Docutils processing on the system.

2. ./docutils.conf: This is a project-specific configuration file, located in the current directory. The Docutils front end has to be executed from the directory containing this configuration file for it to take effect (note that this directory may differ from the location of the source files).

3. ~/.docutils: This is a user-specific configuration file, located in the user's home directory.

If more than one configuration file is found, all will be read and later entries will override earlier ones. [12] For example, a "stylesheet" entry in a user-specific configuration file will override a "stylesheet" entry in the system-wide file.

The default implicit config file paths can be overridden by the DOCUTILSCONFIG environment variable. DOCUTILSCONFIG should contain a colon-separated (semicolon-separated on Windows) sequence of config file paths to search for; leave it empty to disable implicit config files altogether. Tilde-expansion is performed on paths. Paths are interpreted relative to the current working directory. Empty path items are ignored.

In addition, configuration files may be explicitly specified with the --config command-line option. These configuration files are read after the three implicit ones listed above (or the ones defined by the DOCUTILSCONFIG environment variable), and its entries will have priority.

Configuration File Syntax

Configuration files are UTF-8-encoded text files. The configparser module from Python's standard library is used to read them. From its documentation:

A configuration file consists of sections, each led by a [section] header, followed by key/value entries separated by a specific string (= or : by default). […] Leading and trailing whitespace is removed from keys and values. […] Configuration files may include comments, prefixed by specific characters (# and ; by default).

The following conventions apply to Docutils configuration files:

• Configuration file entry names correspond to internal runtime settings. Underscores ("_") and hyphens ("-") can be used interchangeably in entry names; hyphens are automatically converted to underscores. Entries with non-applicable or misspelled entry names are silently ignored.

• For boolean settings (switches), the following values are recognized (case-independent):

  True:

  "true", "yes", "on", "1"

  False:

  "false", "no", "off", "0", "" (no value)

• Lists are specified either comma- or colon-separated:

  comma-separated:

  strip_classes, strip_elements_with_classes, smartquotes_locales, stylesheet, stylesheet_dirs, stylesheet_path, use_bibtex

  Whitespace around list values is stripped, so you can write, e.g.,

  strip-classes: ham,eggs,
  strip-elements-with-classes: sugar, salt, flour
  stylesheet: html4css1.css,
              math.css,
              style sheet with spaces.css

  colon-separated:

  ignore, prune, sources, expose_internals

  Whitespace around the delimiter is not stripped. Write, e.g.,

  expose_internals: source:line

• No format string interpolation is done.

# These entries affect all processing:
[general]
source-link: yes
datestamp: %Y-%m-%d %H:%M UTC
generator: on

# These entries affect HTML output:
[html writers]
embed-stylesheet: no

[html4css1 writer]
stylesheet-path: docutils/writers/html4css1/html4css1.css
field-name-limit: 20

[html5 writer]
stylesheet-dirs: docutils/writers/html5_polyglot/
stylesheet-path: minimal.css, responsive.css

Configuration File Sections & Entries

Below are the Docutils runtime settings, listed by config file section. Sections correspond to Docutils components (module name or alias; always in lowercase letters).

Each Docutils application uses a specific set of components; corresponding configuration file sections are "active" when the application is used.

Configuration sections are applied in general-to-specific order:

1. [general]

2. [parsers], parser dependencies, and the section specific to the Parser used ("[... parser]").

3. [readers], reader dependencies, and the section specific to the Reader used ("[... reader]"). For example, [pep reader] depends on [standalone reader].

4. [writers], writer family ("[... writers]"; if applicable), writer dependencies, and the section specific to the writer used ("[... writer]"). For example, [pep_html writer] depends on [html writers] and [html4css1 writer].

5. [applications], application dependencies, and the section specific to the Application (front-end tool) in use ("[... application]").

Since any setting may be specified in any section, this ordering allows component- or application-specific overrides of earlier settings. For example, there may be Reader-specific overrides of general settings; Writer-specific overrides of Parser settings; Application-specific overrides of Writer settings; and so on.

If multiple configuration files are applicable, the process is completed (all sections are applied in the order given) for each one before going on to the next. For example, a "[pep_html writer] stylesheet" setting in an earlier configuration file would be overridden by an "[html4css1 writer] stylesheet" setting in a later file.

Individual configuration sections and settings are described in the following sections. Some knowledge of Python is assumed for some attributes.

auto_id_prefix

Prefix prepended to all auto-generated identifier keys generated within the document, after id_prefix. Ensure the value conforms to the restrictions on identifiers in the output format, as it is not subjected to the identifier normalization.

A trailing "%" is replaced with the tag name (new in Docutils 0.16).

Default:

"%" (changed from "id" in Docutils 0.18).

Option:

--auto-id-prefix (hidden, intended mainly for programmatic use).

datestamp

Include a time/datestamp in the document footer. Contains a format string for Python's time.strftime().

Configuration file entry examples:

# Equivalent to --date command-line option, results in
# ISO 8601 extended format datestamp, e.g. "2001-12-21":
datestamp: %Y-%m-%d

# Equivalent to --time command-line option, results in
# date/timestamp like "2001-12-21 18:43 UTC":
datestamp: %Y-%m-%d %H:%M UTC

# Disables datestamp; equivalent to --no-datestamp:
datestamp:

Default:

None.

Options:

--date, -d, --time, -t, --no-datestamp.

debug

Report debug-level system messages.

Default: None (disabled). Options: --debug, --no-debug.

dump_internals

At the end of processing, write all internal attributes of the document (document.__dict__) to stderr.

Default: None (disabled). Option: --dump-internals (hidden, for development use only).

dump_pseudo_xml

At the end of processing, write the pseudo-XML representation of the document to stderr.

Default: None (disabled). Option: --dump-pseudo-xml (hidden, for development use only).

dump_settings

At the end of processing, write all Docutils settings to stderr.

Default: None (disabled). Option: --dump-settings (hidden, for development use only).

dump_transforms

At the end of processing, write a list of all transforms applied to the document to stderr.

Default: None (disabled). Option: --dump-transforms (hidden, for development use only).

error_encoding

The text encoding [13] for error output.

Default:

The encoding reported by sys.stderr, locale encoding, or "ascii".

Options:

--error-encoding, -e.

error_encoding_error_handler

The error handler for unencodable characters in error output. Acceptable values are the Error Handlers of Python's "codecs" module. See also output_encoding_error_handler.

Default:

"backslashreplace"

Options:

--error-encoding-error-handler, --error-encoding, -e.

exit_status_level

A system message level threshold; non-halting system messages at or above this level will produce a non-zero exit status at normal exit. Exit status is the maximum system message level plus 10 (11 for INFO, etc.).

Default: 5 (disabled). Option: --exit-status.

expose_internals

List of internal attributes (colon-separated) to expose as external attributes (with "internal:" namespace prefix). Values are appended. [12]

Default: empty list. Option: --expose-internal-attribute (hidden, for development use only).

footnote_backlinks

Enable backlinks from footnotes and citations to their references.

Default:

True.

Options:

--footnote-backlinks, --no-footnote-backlinks.

generator

Include a "Generated by Docutils" credit and link in the document footer.

Default:

None (disabled).

Options:

--generator, -g, --no-generator.

halt_level

The threshold at or above which system messages are converted to exceptions, halting execution immediately. If traceback is set, the exception will propagate; otherwise, Docutils will exit.

See also report_level.

Default:

4 (severe).

Options:

--halt, --strict (same as --halt=info).

id_prefix

Prefix prepended to all identifier keys generated within the document. Ensure the value conforms to the restrictions on identifiers in the output format, as it is not subjected to the identifier normalization. See also auto_id_prefix.

Default:

"" (no prefix).

Option:

--id-prefix (hidden, intended mainly for programmatic use).

input_encoding

The text encoding [13] for input.

Default:

utf-8 (changed from None (auto-detect) in Docutils 0.22).

Option:

--input-encoding (shortcut -i removed in Docutils 0.22).

input_encoding_error_handler

The error handler for undecodable characters in the input. Acceptable values are the Error Handlers of Python's "codecs" module, including:

strict

Raise an exception in case of an encoding error.

replace

Replace malformed data with the official Unicode replacement character, U+FFFD.

ignore

Ignore malformed data and continue without further notice.

The error handler may also be appended to the input_encoding setting, delimited by a colon, e.g. --input-encoding=ascii:replace.

Default: "strict". Options: --input-encoding-error-handler.

language_code

Case-insensitive language tag as defined in BCP 47.

Sets the document language, also used for localized directive and role names as well as Docutils-generated text.

A typical language identifier consists of a 2-letter language code from ISO 639 (3-letter codes can be used if no 2-letter code exists). The language identifier can have an optional subtag, typically for variations based on country (from ISO 3166 2-letter country codes). Avoid subtags except where they add useful distinguishing information. Examples of language tags include "fr", "en-GB", "pt-br" (the same as "pt-BR"), and "de-1901" (German with pre-1996 spelling).

The language of document parts can be specified with a "language-<language tag>" class attribute, e.g. .. class:: language-grc for a quote in Ancient Greek.

Default: "en" (English). Options: --language, -l.

output_path

Output file path or "-" for stdout.

Obsoletes the second positional argument and the internal _destination setting (cf. Future changes in the RELEASE-NOTES).

Default:

None (write to stdout).

Options:

--output-path, --output.

New in Docutils 0.20. Renamed from "output" to "output_path" in Docutils 0.22.

output_encoding

The text encoding [13] for output. The special value "unicode" can be used with the Publisher convenience functions publish_string() and publish_from_doctree() to skip encoding and return a str instance instead of bytes.

This setting is ignored by the ODF/ODT Writer which always usues UTF-8.

Default:

"utf-8".

Option:

--output-encoding (shortcut -o removed in Docutils 0.22).

output_encoding_error_handler

The error handler for unencodable characters in the output. Acceptable values are the Error Handlers of Python's "codecs" module, including:

strict

Raise an exception in case of an encoding error.

replace

Replace malformed data with a suitable replacement marker, such as "?".

ignore

Ignore malformed data and continue without further notice.

xmlcharrefreplace

Replace with the appropriate XML character reference, such as "&#8224;".

backslashreplace

Replace with backslash escape sequences, such as "\u2020".

The error handler may also be appended to the output_encoding setting using a colon as delimiter, e.g. --output-encoding=ascii:xmlcharrefreplace.

Default: "strict". Options: --output-encoding-error-handler.

record_dependencies

Path to a file where Docutils will write a list of files that were required to generate the output, e.g. included files or embedded stylesheets. [1] The format is one path per line with forward slashes as separator, the encoding is UTF-8.

Set it to "-" in order to write dependencies to stdout.

This option is particularly useful in conjunction with programs like make using Makefile rules like:

ham.html: ham.rst $(shell cat hamdeps.rst)
  rst2html --record-dependencies=hamdeps.rst ham.rst > ham.html

If the filesystem encoding differs from UTF-8, replace the cat command with a call to a converter, e.g.:

$(shell iconv -f utf-8 -t latin1 hamdeps.rst)

Default: None (disabled). Option: --record-dependencies.

report_level

Report system messages at or higher than the given severity level:

1 info,  2 warning,  3 error,  4 severe,  5 none

See also halt_level.

Default:

2 (warning).

Options:

--report, -r (with level as number or name)

--verbose, -v (same as --report=1)

--quiet, -q (same as --report=5)

root_prefix

Base directory, prepended to a filesystem path starting with "/" when including files with the "include", "raw", or "csv-table" directives. Also applied to the "uri" attribute of an <image> or <figure> starting with "/" when it is converted to a local filesystem path. Not applied to absolute Windows paths and file: URIs.

Example:

The HTML server for a documentation project serves files from the "DocumentRoot" /var/www/html/. Image files are stored in a dedicated directory /var/www/html/pictures/.

With root-prefix=/var/www/html, the rST "image" directive

.. image:: /pictures/mylogo.png

works for LaTeX output and HTML output with embedded images as well as for HTML output with images included via URI reference.

Default:

"" (empty string).

Option:

--root-prefix.

New in Docutils 0.21.

sectnum_xform

Enable automatic section numbering by Docutils (SectNum transform associated with the "sectnum" directive).

If disabled, the SectNum transform adds the internal settings sectnum_depth, sectnum_start, sectnum_prefix, and sectnum_suffix to store the respective "sectnum" directive options. Section numbers may be added to the output by the renderer (e.g. by CSS style rules or LaTeX).

Default:

True.

Options:

--section-numbering, --no-section-numbering.

source_link

Include a "View document source" link in the document footer. The URL will be relative to the output_path (if specified) or the current work directory.

Default:

None (disabled).

Options:

--source-link, -s, --no-source-link.

source_url

An explicit URL for a "View document source" link, used verbatim.

Default:

None (compute from source_link).

Options:

--source-url, --no-source-link.

strict_visitor

When processing a document tree with the Visitor pattern, raise an error if a writer does not support a node type listed as optional. For transitional development use.

Default:

None (disabled).

Option:

--strict-visitor (hidden, for development use only).

strip_classes

List of "classes" attribute values (comma-separated) that will be removed from all elements in the document tree. Values are appended. [12]

Allows eliding class values that interfere with, e.g, CSS rules from 3rd party tools/frameworks.

Default: empty list. Option: --strip-class.

strip_comments

Enable or disable the removal of comment elements from the document tree.

Default:

None (disabled).

Options:

--strip-comments, --leave-comments.

strip_elements_with_classes

List of "classes" attribute values (comma-separated). Values are appended. [12] Matching elements are removed from the document tree (by the StripClassesAndElements transform).

Default: empty list. Option: --strip-elements-with-class.

title

The document title as metadata which does not become part of the document body. Stored as the document's title attribute. For example, in HTML output the metadata document title appears in the title bar of the browser window.

This setting overrides a displayed document title and is overridden by a "title" directive.

Default:

None (the displayed document title).

Option:

--title.

toc_backlinks

Enable backlinks from section titles to table of contents entries ("entry"), to the top of the ToC ("top"), or disable (False).

Default:

"entry".

Options:

--toc-entry-backlinks, --toc-top-backlinks, --no-toc-backlinks.

traceback

Enable or disable Python tracebacks when system messages with a severity above the halt_level and other exceptions occur. Useful for debugging, and essential for issue reports. Exceptions are allowed to propagate, instead of being caught and reported (in a user-friendly way) by Docutils.

Default:

None (disabled). [2]

Options:

--traceback, --no-traceback.

warning_stream

Path [14] to a file for the output of system messages (warnings).

Default: None (stderr). Option: --warnings.

file_insertion_enabled

Enable directives inserting the contents of external files, such as "include" directive or the "raw" and "csv-table" directives with option "url" or "file". A "warning" system message (including the directive text) is inserted instead. (See also raw_enabled for another security-relevant setting.)

Default:

True.

Options:

--file-insertion-enabled, --no-file-insertion.

line_length_limit

Maximal number of characters in an input line or "substitution" definition. To prevent extraordinary high processing times or memory usage for certain input constructs, a "warning" system message is inserted instead.

Default: 10 000. Option: --line-length-limit

New in Docutils 0.17.

raw_enabled

Enable the "raw" directive. A "warning" system message (including the directive text) is inserted instead. See also file_insertion_enabled for another security-relevant setting.

Default: True. Options: --raw-enabled, --no-raw.

validate

Validate the parsing result. Report elements that do not comply with the restrictions set out in the Docutils Generic document type definition.

Default: False. Options: --validate, --no-validation.

[restructuredtext parser]

[myst parser]

Parser for Markdown (CommonMark) with rST-compatibility extensions provided by the 3rd party package myst-docutils. See MyST with Docutils and MyST's Sphinx configuration options. (Some settings are not applicable with Docutils, docutils --parser=myst --help shows available options.)

[pycmark parser]

Parser for Markdown (CommonMark) provided by the 3rd party package pycmark. Currently no configuration settings.

[recommonmark parser]

Parser for Markdown (CommonMark) provided by the 3rd party package recommonmark.

Currently no configuration settings.

[xml parser]

The Docutils XML parser processes an XML representation of a Docutils Document Tree (e.g. the output of the Docutils XML writer).

New in Docutils 0.22

[standalone reader]

[pep reader]

[docutils_xml writer]

[html writers]

Common settings for the Docutils HTML writers.

<a class="reference" href="mailto:abc&#37;&#52;&#48;example&#46;org">
abc<span>&#64;</span>example<span>&#46;</span>org</a>