# Docutils Configuration

Author: | David Goodger
Contact: | docutils-develop@lists.sourceforge.net
Revision: | 8115
Date: | 2017-06-16
Copyright: | This document has been placed in the public domain.

Contents

- Configuration Files
- Configuration File Syntax
  - Example
- Configuration File Sections & Entries
  - [general]
    - auto_id_prefix
    - datestamp
    - debug
    - dump_internals
    - dump_pseudo_xml
    - dump_settings
    - dump_transforms
    - error_encoding
    - error_encoding_error_handler
    - exit_status_level
    - expose_internals
    - footnote_backlinks
    - generator
    - halt_level
    - id_prefix
    - input_encoding
    - input_encoding_error_handler
    - language_code
    - output_encoding
    - output_encoding_error_handler
    - record_dependencies
    - report_level
    - sectnum_xform
    - source_link
    - source_url
    - strict_visitor
    - strip_classes
    - strip_comments
    - strip_elements_with_classes
    - title
    - toc_backlinks
    - traceback
    - warning_stream
  - [parsers]
    - [restructuredtext parser]
      - character_level_inline_markup
      - file_insertion_enabled
      - pep_references
      - pep_base_url
      - pep_file_url_template
      - raw_enabled
      - rfc_references
      - rfc_base_url
      - smart_quotes
      - smartquotes_locales
      - syntax_highlight
      - tab_width
      - trim_footnote_reference_space
  - [readers]
    - [standalone reader]
      - docinfo_xform
      - doctitle_xform
      - sectsubtitle_xform
    - [pep reader]
  - [writers]
    - [docutils_xml writer]
      - doctype_declaration
      - indents
      - newlines
      - xml_declaration
    - [html4css1 writer]
      - attribution
      - cloak_email_addresses
      - compact_lists
      - compact_field_lists
      - embed_stylesheet
      - field_name_limit
      - footnote_references
      - initial_header_level
      - math_output
      - option_limit
      - stylesheet
      - stylesheet_dirs
      - stylesheet_path
      - table_style
      - template
      - xml_declaration
      - [pep_html writer]
        - no_random
        - pep_home
        - python_home
      - [s5_html writer]
        - hidden_controls
        - current_slide
        - overwrite_theme_files
        - theme
        - theme_url
        - view_mode
    - [html5 writer]
    - [latex2e writer]
      - use_latex_toc
      - use_latex_docinfo
      - docutils_footnotes
      - use_latex_citations
      - use_latex_abstract
      - hyperlink_color
      - hyperref_options
      - documentclass
      - documentoptions
      - font_encoding
      - embed_stylesheet
      - stylesheet
      - stylesheet_dirs
      - stylesheet_path
      - latex_preamble
      - footnote_references
      - attribution
      - compound_enumerators
      - literal_block_env
      - section_prefix_for_enumerators
      - section_enumerator_separator
      - table_style
      - template
      - [xetex writer]
    - [odf_odt writer]
      - stylesheet
      - odf-config-file
      - cloak-email-addresses
      - no-cloak-email-addresses
      - table-border-thickness
      - add-syntax-highlighting
      - no-syntax-highlighting
      - create-sections
      - no-sections
      - create-links
      - no-links
      - endnotes-end-doc
      - no-endnotes-end-doc
      - generate-list-toc
      - generate-oowriter-toc
      - custom-odt-header
      - custom-odt-footer
    - [pseudoxml writer]
  - [applications]
    - [buildhtml application]
      - ignore
      - prune
      - recurse
      - silent
    - [docfactory application]
  - Other Settings
    - Command-Line Only
      - config
    - Internal Settings
      - _config_files
      - _directories
      - _disable_config
      - _destination
      - _source
- Old-Format Configuration Files

# Configuration Files

Configuration files are used for persistent customization; they can be set once and take effect every time you use a front-end tool. Configuration file settings override the built-in defaults, and command-line options override all.

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 may have nothing to do with the location of the source files). Settings in the project-specific configuration file will override corresponding settings in the system-wide file.
3. `~/.docutils`: This is a user-specific configuration file, located in the user's home directory. Settings in this file will override corresponding settings in both the system-wide and project-specific configuration files.

If more than one configuration file is found, all will be read but later entries will override earlier ones. 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, a configuration file may be explicitly specified with the "--config" command-line option. This configuration file is 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.py module from Python's standard library is used to read them. From its documentation:

> The configuration file consists of sections, lead by a "[section]" header and followed by "name: value" entries, with continuations in the style of RFC 822; "name=value" is also accepted. Note that leading whitespace is removed from values. ... Lines beginning with "#" or ";" are ignored and may be used to provide comments.

Note

No format string interpolation is done.

Configuration file entry names correspond to internal runtime settings. Underscores ("_") and hyphens ("-") can be used interchangably in entry names; hyphens are automatically converted to underscores.

For on/off switch settings (booleans), the following values are recognized:

On: | "true", "yes", "on", "1"
Off: | "false", "no", "off", "0", "" (no value)

List values can be comma- or colon-delimited.

strip_classes, strip_elements_with_classes, stylesheet, and stylesheet_path use the comma as delimiter, whitespace around list values is stripped.

    strip-classes: ham,eggs,
    strip-elements-with-classes: sugar, salt, flour
    stylesheet: html4css1.css,
                math.css,
                style with spaces.css
    stylesheet-path: ../styles/my.css, ../styles/funny.css

expose_internals, ignore and prune use the colon as delimiter and do not strip whitespace:

    expose_internals: b:c:d

## Example

This is the contents of the `tools/docutils.conf` configuration file supplied with Docutils:

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

    # These entries affect HTML output:
    [html4css1 writer]
    # Required for docutils-update, the website build system:
    stylesheet-path: ../docutils/writers/html4css1/html4css1.css
    embed-stylesheet: no
    field-name-limit: 20

Individual configuration sections and settings are described in the following section.

# Configuration File Sections & Entries

Below are the Docutils runtime settings, listed by config file section. Any setting may be specified in any section, but only settings from active sections will be used. Sections correspond to Docutils components (module name or alias; section names are always in lowercase letters). Each Docutils application uses a specific set of components; corresponding configuration file sections are applied when the application is used. Configuration sections are applied in general-to-specific order, as follows:

1. [general]
2. [parsers], parser dependencies, and the section specific to the Parser used ("[... parser]"). Currently, only [restructuredtext parser] is applicable.
3. [readers], reader dependencies, and the section specific to the Reader used ("[... reader]"). For example, [pep reader] depends on [standalone reader].
4. [writers], writer dependencies, and the section specific to the Writer used ("[... writer]"). For example, [pep_html writer] depends on [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.

Some knowledge of Python is assumed for some attributes.

## [general]

Settings in the "[general]" section are always applied.

### auto_id_prefix

Prefix prepended to all auto-generated IDs generated within the document, after id_prefix.

Default: "id". Options: `--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`. See the time module documentation.

Default: None. Options: `--date, -d, --time, -t, --no-datestamp`.

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:

### debug

Report debug-level system messages.

Default: don't (None). Options: `--debug, --no-debug`.

### dump_internals

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

Default: don't (None). Options: `--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: don't (None). Options: `--dump-pseudo-xml` (hidden, for development use only).

### dump_settings

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

Default: don't (None). Options: `--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: don't (None). Options: `--dump-transforms` (hidden, for development use only).

### error_encoding

The text encoding for error output.

Default: "ascii". Options: `--error-encoding, -e`.

### error_encoding_error_handler

The error handler for unencodable characters in error output. See output_encoding_error_handler for acceptable values.

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: disabled (5). Options: `--exit-status`.

### expose_internals

List of internal attribues to expose as external attributes (with "internal:" namespace prefix). To specify multiple attributes in configuration files, use colons to separate names; on the command line, the option may be used more than once.

Default: don't (None). Options: `--expose-internal-attribute` (hidden, for development use only).

### footnote_backlinks

Enable or disable backlinks from footnotes and citations to their references.

Default: enabled (True). Options: `--footnote-backlinks, --no-footnote-backlinks`.

### generator

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

Default: off (None). 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.

Default: severe (4). Options: `--halt, --strict`.

### id_prefix

Prefix prepended to all IDs generated within the document. See also auto_id_prefix.

Default: "" (empty). Options: `--id-prefix` (hidden, intended mainly for programmatic use).

### input_encoding

The text encoding for input.

Default: auto-detect (None). Options: `--input-encoding, -i`.

### input_encoding_error_handler

The error handler for undecodable characters in the input. Acceptable values include:

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.

Acceptable values are the same as for the "error" parameter of Python's `unicode` function; other values may be defined in applications or in future versions of Python.

Default: "strict". Options: `--input-encoding-error-handler, --input-encoding, -i`.

### 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-el-polyton` for a quote in polytonic Greek.

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

### output_encoding

The text encoding for output.

Default: "UTF-8". Options: `--output-encoding, -o`.

### output_encoding_error_handler

The error handler for unencodable characters in the output. Acceptable values include:

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 backslashed escape sequences, such as "`\u2020`".

Acceptable values are the same as for the "error" parameter of Python's `encode` string method; other values may be defined in applications or in future versions of Python.

Default: "strict". Options: `--output-encoding-error-handler, --output-encoding, -o`.

### 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 [4]. [2] The format is one path per line with forward slashes as separator, the encoding is `utf8`.

Set 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.txt $(shell cat hamdeps.txt)
      rst2html.py --record-dependencies=hamdeps.txt ham.txt ham.html

If the filesystem encoding differs from utf8, replace the `cat` command with a call to a converter, e.g.:

    $(shell iconv -f utf8 -t latin1 hamdeps.txt)

Default: None. Option: `--record-dependencies`.

### report_level

Report system messages at or higher than <level>:

1 info 2 warning 3 error 4 severe 5 none

Default: warning (2). Options: `--report, -r, --verbose, -v, --quiet, -q`.

### sectnum_xform

Enable or disable automatic section numbering by Docutils (docutils.transforms.parts.SectNum) associated with the sectnum directive.

If disabled, section numbers might be added to the output by the renderer (e.g. by LaTeX or via a CSS style definition).

Default: enabled (True). Options: `--section-numbering`, `--no-section-numbering`.

### source_link

Include a "View document source" link in the document footer. URL will be relative to the destination.

Default: don't (None). Options: `--source-link, -s, --no-source-link`.

### source_url

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

Default: compute if source_link (None). 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: disabled (None). Option: `--strict-visitor` (hidden, for development use only).

### strip_classes

Comma-separated list of "classes" attribute values to remove from all elements in the document tree. The command line option may be used more than once.

Warning

Potentially dangerous; use with caution.

Default: disabled (None). Option: `--strip-class`.

### strip_comments

Enable the removal of comment elements from the document tree.

Default: disabled (None). Options: `--strip-comments`, `--leave-comments`.

### strip_elements_with_classes

Comma-separated list of "classes" attribute values; matching elements are removed from the document tree. The command line option may be used more than once.

Warning

Potentially dangerous; use with caution.

Default: disabled (None). Option: `--strip-element-with-class`.

### title

The document title as metadata, which does not become part of the document body. It overrides a document-supplied title. For example, in HTML output the metadata document title appears in the title bar of the browser window.

Default: none. Option: `--title`.

### toc_backlinks

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

Default: "entry". Options: `--toc-entry-backlinks, --toc-top-backlinks, --no-toc-backlinks`.

### traceback

Enable Python tracebacks when halt-level system messages 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: disabled (None) unless Docutils is run programmatically using the Publisher Interface. Options: `--traceback, --no-traceback`.

### warning_stream

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

Default: stderr (None). Options: `--warnings`.

## [parsers]

Docutils currently supports only one parser, for reStructuredText.

### [restructuredtext parser]

#### character_level_inline_markup

Experimental setting to relax the inline markup recognition rules requiring whitespace or punctuation around inline markup.

Allows character level inline markup without escaped whithespace and is especially suited for langauges that do not use whitespace to separate words (e.g. Japanese, Chinese).

Warning

Potentially dangerous; use with caution.

When changing this setting to "True", inline markup charactes in URLs, names and formulas must be escaped to prevent recognition and possible errors. Examples:

    http://rST_for_all.html (hyperlinks to rST_ and for_)
    x_2, inline_markup      (hyperlinks to x_ and inline_)
    2*x                     (starts emphasised text)
    a|b                     (starts a substitution reference)

Default: disabled (False). Options: `--character-level-inline-markup, --word-level-inline-markup`.

New in Docutils 0.13.

#### file_insertion_enabled

Enable or disable directives that insert the contents of external files, such as the "include" & "raw". A "warning" system message (including the directive text) is inserted instead. (See also raw_enabled for another security-relevant setting.)

Default: enabled (True). Options: `--file-insertion-enabled, --no-file-insertion`.

#### pep_references

Recognize and link to standalone PEP references (like "PEP 258").

Default: disabled (None); enabled (True) in PEP Reader. Options: `--pep-references`.

#### pep_base_url

Base URL for PEP references.

Default: "http://www.python.org/peps/". Option: `--pep-base-url`.

#### pep_file_url_template

Template for PEP file part of URL, interpolated with the PEP number and appended to pep_base_url.

Default: "pep-%04d". Option: `--pep-file-url`.

#### raw_enabled

Enable or disable 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: enabled (True). Options: `--raw-enabled, --no-raw`.

#### rfc_references

Recognize and link to standalone RFC references (like "RFC 822").

Default: disabled (None); enabled (True) in PEP Reader. Options: `--rfc-references`.

#### rfc_base_url

Base URL for RFC references.

Default: "http://www.faqs.org/rfcs/". Option: `--rfc-base-url`.

#### smart_quotes

Activate the SmartQuotes transform to change straight quotation marks to typographic form. Quote characters are selected according to the language of the current block element (see language_code, smartquotes_locales, and the pre-defined quote sets).

Also changes consecutive runs of hyphen-minus and full stops (`---`, `--`, `...`) to em-dash, en-dash and ellipsis Unicode characters respectively.

Supported values:

booleans (yes/no)
  Use smart quotes?
alt (or "alternative")
  Use alternative quote set (if defined for the language).

Default: "no". Option: `--smart-quotes`.

New in Docutils 0.10.

#### smartquotes_locales

Typographical quotes used by the SmartQuotes transform.

A comma-separated list with language tag and a set of four quotes (primary open/close, secondary open/close)smartquotes_locales. (If more than one character shall be used for a quote (e.g. padding in French quotes), a colon-separated list may be used.)

Example:

  Ensure a correct leading apostrophe in `'s Gravenhage` in Dutch (at the cost of incorrect opening single quotes) and set French quotes to double and single guillemets with inner padding:

      smartquote-locales: nl: „”’’,
                          fr: « : »:‹ : ›

Default: None. Option: `--smartquotes-locales`.

New in Docutils 0.14.

#### syntax_highlight

Token type names used by Pygments when parsing contents of the code directive and role.

Supported values:

long
  Use hierarchy of long token type names.
short
  Use short token type names. (For use with Pygments-generated stylesheets.)
none
  No code parsing. Use this to avoid the "Pygments not found" warning when Pygments is not installed.

Default: "long". Option: `--syntax-highlight`.

New in Docutils 0.9.

#### tab_width

Number of spaces for hard tab expansion.

Default: 8. Options: `--tab-width`.

#### trim_footnote_reference_space

Remove spaces before footnote references.

Default: don't (None); may be overriden by a writer-specific footnote_references default though.

Options: `--trim-footnote-reference-space, --leave-footnote-reference-space`.

## [readers]

### [standalone reader]

#### docinfo_xform

Enable or disable the bibliographic field list transform (docutils.transforms.frontmatter.DocInfo).

Default: enabled (True). Options: `--no-doc-info`.

#### doctitle_xform

Enable or disable the promotion of a lone top-level section title to document title (and subsequent section title to document subtitle promotion; docutils.transforms.frontmatter.DocTitle).

Default: enabled (True). Options: `--no-doc-title`.

#### sectsubtitle_xform

Enable or disable the promotion of the title of a lone subsection to a subtitle (docutils.transforms.frontmatter.SectSubTitle).

Default: disabled (0). Options: `--section-subtitles, --no-section-subtitles`.

### [pep reader]

The pep_references and rfc_references settings ([restructuredtext parser]) are set on by default.

## [writers]

### [docutils_xml writer]

Caution!

- In Python versions older than 2.7.3 and 3.2.3, the newlines and indents options may adversely affect whitespace; use them only for reading convenience (see http://bugs.python.org/issue4147).
- The XML declaration carries text encoding information. If the encoding is not UTF-8 or ASCII and the XML declaration is missing, standard tools may be unable to read the generated XML.

#### doctype_declaration

Generate XML with a DOCTYPE declaration.

Default: do (1). Options: `--no-doctype`.

#### indents

Generate XML with indents and newlines.

Default: don't (None). Options: `--indents`.

#### newlines

Generate XML with newlines before and after tags.

Default: don't (None). Options: `--newlines`.

#### xml_declaration

Generate XML with an XML declaration. Also defined for the HTML Writer.

Default: do (1). Options: `--no-xml-declaration`.

### [html4css1 writer]

#### attribution

Format for block quote attributions: one of "dash" (em-dash prefix), "parentheses"/"parens", or "none". Also defined for the LaTeX Writer.

Default: "dash". Options: `--attribution`.

#### cloak_email_addresses

Scramble email addresses to confuse harvesters. In the reference URI, the "@" will be replaced by %-escapes (as of RFC 1738). In the visible text (link text) of an email reference, the "@" and all periods (".") will be surrounded by `<span>` tags. Furthermore, HTML entities are used to encode these characters in order to further complicate decoding the email address. For example, "abc@example.org" will be output as:

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

Note

While cloaking email addresses will have little to no impact on the rendering and usability of email links in most browsers, some browsers (e.g. the `links` browser) may decode cloaked email addresses incorrectly.

Default: don't cloak (None). Option: `--cloak-email-addresses`.

#### compact_lists

Remove extra vertical whitespace between items of bullet lists and enumerated lists, when list items are all "simple" (i.e., items each contain one paragraph and/or one "simple" sublist only). The behaviour can be specified directly via "class" attributes (values "compact" and "open") in the document.

Default: enabled (True). Options: `--compact-lists, --no-compact-lists`.

#### compact_field_lists

Remove extra vertical whitespace between items of field lists that are "simple" (i.e., all field bodies each contain at most one paragraph). The behaviour can be specified directly via "class" attributes (values "compact" and "open") in the document.

Default: enabled (True). Options: `--compact-field-lists, --no-compact-field-lists`.

#### embed_stylesheet

Embed the stylesheet in the output HTML file. The stylesheet file must specified by the stylesheet_path setting and must be accessible during processing. Also defined for the LaTeX Writer.

Default: enabled. Options: `--embed-stylesheet, --link-stylesheet`.

#### field_name_limit

The maximum width (in characters) for one-column field names. Longer field names will span an entire row of the table used to render the field list. 0 indicates "no limit". See also option_limit.

Default: 14 (i.e. 14 characters). Option: `--field-name-limit`.

#### footnote_references

Format for footnote references, one of "superscript" or "brackets". Also defined for the LaTeX Writer.

Overrides [3] trim_footnote_reference_space, if applicable. [5]

Default: "brackets". Option: `--footnote-references`.

#### initial_header_level

The initial level for header elements. This does not affect the document title & subtitle; see doctitle_xform.

Default: 1 (for "<h1>"). Option: `--initial-header-level`.

#### math_output

The format of mathematical content (math directive and role) in the output document. Supported values are (case insensitive):

HTML: | Format math in standard HTML enhanced by CSS rules. Requires the `math.css` stylesheet (in the system stylesheet directory) A stylesheet_path can be appended after whitespace, the specified stylesheet(s) will only be referenced or embedded, if required (i.e. if there is mathematical content in the document).

MathJax:

Format math for display with MathJax, a JavaScript-based math rendering engine.

Pro:

  Works across multiple browsers and platforms.

  Large set of supported LaTeX math commands and constructs

Con:

  Rendering requires JavaScript and an Internet connection or local MathJax installation.

A URL pointing to a MathJax library should be appended after whitespace. A warning is given if this is missing.

- It is recommended to install the MathJax library on the same server as the rest of the deployed site files.

  Example: Install the library at the top level of the web server’s hierarchy in the directory `MathJax` and set:

      math-output: mathjax /MathJax/MathJax.js

- The easiest way to use MathJax is to link directly to a public installation. In that case, there is no need to install MathJax locally.

  Downside: Downloads JavaScript code from a third-party site --- opens the door to cross-site scripting attacs!

  Example: MathJax.org recommends `cdnjs.cloudflare.com`:

      math-output: mathjax
                   https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js

  See https://cdnjs.com/about and https://www.cloudflare.com/terms/ for details and terms of use.

- Use a local MathJax installation on the client machine, e.g.:

      math-output: MathJax file:/usr/share/javascript/mathjax/MathJax.js

  This is the fallback if no URL is specified.

MathML:

Embed math content as presentational MathML.

Pro:

  The W3C recommendation for math on the web.

  Self-contained documents (no JavaScript, no external downloads).

Con:

  Docutil's latex2mathml converter supports only a small subset of LaTeX syntax.

  With the "html4css1" writer, the resulting HTML document does not validate, as there is no DTD for MathML + XHTML Transitional. However, MathML-enabled browsers will render it fine.

An external converter can be appended after whitespace, e.g., `--math-output="MathML latexml"`:

blahtexml

  Fast conversion, support for many symbols and environments, but no "align" (or other equation-aligning) environment. (C++)

LaTeXML

  Comprehensive macro support but very slow. (Perl)

TtM

  No "matrix", "align" and "cases" environments. Support may be removed.

LaTeX: | Include literal LaTeX code. The failsave fallback.

Default: "HTML math.css" (The [html5 writer] defaults to "MathML"). Option: `--math-output`.

New in Docutils 0.8.

#### option_limit

The maximum width (in characters) for options in option lists. Longer options will span an entire row of the table used to render the option list. 0 indicates "no limit". See also field_name_limit.

Default: 14 (i.e. 14 characters). Option: `--option-limit`.

#### stylesheet

A comma-separated list of CSS stylesheet URLs, used verbatim. Also defined for the LaTeX Writer.

Overrides also stylesheet-path. [3]

Default: None. Options: `--stylesheet`.

#### stylesheet_dirs

A comma-separated list of directories where stylesheets can be found. Used by the stylesheet_path setting when expanding relative path arguments.

Note: This setting defines a "search path" (similar to the PATH variable for executables). However, the term "path" is already used in the stylesheet_path setting with the meaning of a file location.

Default: the working directory of the process at launch and the directory with default stylesheet files (writer and installation specific). Use the `--help` option to get the exact value. Option: `--stylesheet-directories`.

#### stylesheet_path

A comma-separated list of paths to CSS stylesheets. Relative paths are expanded if a matching file is found in the stylesheet_dirs. If embed_stylesheet is False, paths are rewritten relative to the output HTML file. Also defined for the LaTeX Writer.

Also overrides "stylesheet". [3] Pass an empty string (to either "stylesheet" or "stylesheet_path") to deactivate stylesheet inclusion.

Default: "html4css1.css". Options: `--stylesheet-path`.

#### table_style

Class value(s) added to all tables. Also defined for the LaTeX Writer.

The default CSS sylesheet defines:

borderless
  No borders around the table.
booktabs
  Lines above and below the table and a thin line after the head.
align-left, align-center, align-right
  Align the tables
colwidths-auto

  Delegate the determination of table column widths to the backend (Leave out the `<colgroup>` column specification.)

  Cf. the table directive.

Default: "". Option: `--table-style`.

#### template

Path to template file, which must be encoded in UTF-8. [2] Also defined for the LaTeX Writer.

Default: "template.txt" in the docutils/writers/html4css1/ directory (installed automatically; for the exact machine-specific path, use the `--help` option). Options: `--template`.

#### xml_declaration

Generate XML with an XML declaration. Also defined for the Docutils XML Writer.

Caution!

The XML declaration carries text encoding information. If the encoding is not UTF-8 or ASCII and the XML declaration is missing, standard tools may be unable to read the generated XHTML.

Default: do (1). Options: `--no-xml-declaration`.

#### [pep_html writer]

The PEP/HTML Writer derives from the standard HTML Writer, and shares all settings defined in the [html4css1 writer] section. The "[html4css1 writer]" section of configuration files is processed before the "[pep_html writer]" section.

The PEP/HTML Writer's default for the following settings differ from those of the standard HTML Writer:

stylesheet_path:
  Default: "pep.css"
template:
  Default: `docutils/writers/pep_html/template.txt` in the installation directory. For the exact machine-specific path, use the `--help` option.

##### no_random

Do not use a random banner image. Mainly used to get predictable results when testing.

Default: random enabled (None). Options: `--no-random` (hidden).

##### pep_home

Home URL prefix for PEPs.

Default: current directory ("."). Options: `--pep-home`.

##### python_home

Python's home URL.

Default: parent directory (".."). Options: `--python-home`.

#### [s5_html writer]

The S5/HTML Writer derives from the standard HTML Writer, and shares all settings defined in the [html4css1 writer] section. The "[html4css1 writer]" section of configuration files is processed before the "[s5_html writer]" section.

The S5/HTML Writer's default for the following settings differ from those of the standard HTML Writer:

compact_lists:
  Default: disable compact lists.
template:
  Default: `docutils/writers/s5_html/template.txt` in the installation directory. For the exact machine-specific path, use the `--help` option.

##### hidden_controls

Auto-hide the presentation controls in slideshow mode, or or keep them visible at all times.

Default: auto-hide (1). Options: `--hidden-controls`, `--visible-controls`.

##### current_slide

Enable or disable the current slide indicator ("1/15").

Default: disabled (None). Options: `--current-slide`, `--no-current-slide`.

##### overwrite_theme_files

Allow or prevent the overwriting of existing theme files in the `ui/<theme>` directory. This has no effect if "theme_url" is used.

Default: keep existing theme files (None). Options: `--keep-theme-files`, `--overwrite-theme-files`.

##### theme

Name of an installed S5 theme, to be copied into a `ui/<theme>` subdirectory, beside the destination file (output HTML). Note that existing theme files will not be overwritten; the existing theme directory must be deleted manually. Also overrides the "theme_url" setting. [3]

Default: "default". Option: `--theme`.

##### theme_url

The URL of an S5 theme directory. The destination file (output HTML) will link to this theme; nothing will be copied. Also overrides the "theme" setting. [3]

Default: None. Option: `--theme-url`.

##### view_mode

The initial view mode, either "slideshow" or "outline".

Default: "slidewhow". Option: `--view-mode`.

### [html5 writer]

The html5 writer uses the settings described in the [html4css1 writer] section with the following exceptions:

Removed options:
  field_name_limit, option_limit.

Different default for:

math_output
  Default: "MathML"
stylesheet_path:
  Default: "minimal.css,plain.css"
stylesheet_dirs:
  Default: Installation-dependent. Use the --help option to get the exact value.

New in Docutils 0.13.

### [latex2e writer]

#### use_latex_toc

To get pagenumbers in the table of contents, it must be generated by LaTeX. Usually latex must be run twice to get numbers correct.

Default: on. Options: `--use-latex-toc, --use-docutils-toc`.

#### use_latex_docinfo

Attach author and date to the document title instead of the bibliographic fields.

Default: off. Options: `--use-latex-docinfo, --use-docutils-docinfo`.

#### docutils_footnotes

Use the Docutils-specific macros `\DUfootnote` and `\DUfootnotetext` for footnotes.

Default: on. Option: `--docutils-footnotes`.

#### use_latex_citations

Use cite for citations instead of a simulation with figure-floats.

Default: off. Options: `--use-latex-citations, --figure-citations`.

#### use_latex_abstract

Use LaTeX abstract environment for the document's abstract.

Default: off. Options: `--use-latex-abstract, --topic-abstract`.

#### hyperlink_color

Color of any hyperlinks embedded in text.

- "0" or "false" disable coloring of links. (Links will be marked by red boxes that are not printed),
- "black" results in “invisible“ links,

Set hyperref_options to "draft" to completely disable hyperlinking.

Default: "blue". Option: `--hyperlink-color`.

#### hyperref_options

Options for the hyperref TeX package. If hyperlink_color is not "false", the expansion of

    'colorlinks=true,linkcolor=%s,urlcolor=%s' % (
       hyperlink_color, self.hyperlink_color

is prepended.

Default: "". Option: `--hyperref-options`.

#### documentclass

Specify LaTeX documentclass.

Default: "article". Option: `--documentclass`.

#### documentoptions

Specify document options. Multiple options can be given, separated by commas.

Default: "a4paper". Option: `--documentoptions`.

#### font_encoding

Specify LaTeX font encoding. Multiple options can be given, separated by commas. The last value becomes the document default. Possible values are "", "T1", "OT1", "LGR,T1" or any other combination of LaTeX font encodings.

Default: "T1". Option: `--font-encoding`.

#### embed_stylesheet

Embed the stylesheet(s) in the header of the output file. The stylesheets must be accessible during processing. Currently, this fails if the file is not available via the given path (i.e. the file is not searched in the TeX input path). Also defined for the HTML Writer (with default on).

Default: off. Options: `--embed-stylesheet, --link-stylesheet`.

#### stylesheet

A comma-separated list of style files. Also defined for the HTML Writer.

Overrides also stylesheet_path. [3]

If embed_stylesheet is False (default), the stylesheet files are referenced with `\usepackage` (extension `.sty` or no extension) or `\input` (any other extension).

LaTeX will search the specified files in the TeX input path.

Default: no stylesheet (""). Option: `--stylesheet`.

#### stylesheet_dirs

A comma-separated list of directories where stylesheets can be found. Used by the stylesheet_path setting.

Note: This setting defines a "search path" (similar to the PATH variable for executables). However, the term "path" is already used in the stylesheet_path setting with the meaning of a file location.

Default: the working directory of the process at launch and the directory with default stylesheet files (writer and installation specific). Use the `--help` option to get the exact value. Option: `--stylesheet-directories`.

#### stylesheet_path

A comma-separated list of style files. Relative paths are expanded if a matching file is found in the stylesheet_dirs. If embed_stylesheet is False, paths are rewritten relative to the output file path. Run `latex` from the directory containing the output file.

The stylesheet option is preferred for files in the TeX input path.

Also defined for the HTML Writer.

Also overrides stylesheet. [3]

Default: no stylesheet (""). Option: `--stylesheet-path`.

#### latex_preamble

LaTeX code that will be inserted in the document preamble. Can be used to load packages with options or (re-) define LaTeX macros without writing a custom style file (new in Docutils 0.7).

Default: Load the "PDF standard fonts" (Times, Helvetica, Courier):

    \usepackage{mathptmx} % Times
    \usepackage[scaled=.90]{helvet}
    \usepackage{courier}

Option: `--latex-preamble`.

#### footnote_references

Format for footnote references: one of "superscript" or "brackets". Also defined for the HTML Writer.

Overrides [3] trim_footnote_reference_space, if applicable [5].

Default: "superscript". Option: `--footnote-references`.

#### attribution

See attribution [html4css1 writer].

#### compound_enumerators

Enable or disable compound enumerators for nested enumerated lists (e.g. "1.2.a.ii").

Default: disabled (None). Options: `--compound-enumerators`, `--no-compound-enumerators`.

#### literal_block_env

When possibile[1], use the specified environment for literal blocks.

Default: "" (quoting of whitespace and special chars). Option: `--literal-block-env`.

[1] | A literal-block element, when processed by a Docutils writer might have it's origin in literal block following "::" or a `.. parsed-literal::` directive. A LaTeX verbatim environment is only usable if there is no other markup contained in the literal-block.

#### section_prefix_for_enumerators

Enable or disable section ("." subsection ...) prefixes for compound enumerators. This has no effect unless compound_enumerators are enabled.

Default: disabled (None). Options: `--section-prefix-for-enumerators`, `--no-section-prefix-for-enumerators`.

#### section_enumerator_separator

The separator between section number prefix and enumerator for compound enumerated lists (see compound_enumerators).

Generally it isn't recommended to use both sub-sections and nested enumerated lists with compound enumerators. This setting avoids ambiguity in the situation where a section "1" has a list item enumerated "1.1", and subsection "1.1" has list item "1". With a separator of ".", these both would translate into a final compound enumerator of "1.1.1". With a separator of "-", we get the unambiguous "1-1.1" and "1.1-1".

Default: "-". Option: `--section-enumerator-separator`.

#### table_style

Specify the default style for tables Also defined for the HTML Writer.

Supported values:

standard
  Borders around all cells.
booktabs
  A line above and below the table and one after the head.
borderless
  No borders.
align-left, align-center, align-right
  Align tables.
colwidths-auto, colwidths-given

  Default value for column width determination by LaTeX or Docutils. Override with the table directive's :widths: option.

  Warning

  `colwidths-auto` is only suited for tables with simple cell content.

  LaTeX puts the content of auto-sized columns on one line (merging paragraphs) and may fail with complex content.

Default: "standard". Option: `--table-style`.

#### template

Path to template file, which must be encoded in UTF-8. [2] Also defined for the HTML Writer.

Default: "default.tex" in the docutils/writers/latex2e/ directory (installed automatically; for the exact machine-specific path, use the `--help` option). Options: `--template`.

#### [xetex writer]

The xetex writer derives from the latex2e writer, and shares all settings defined in the [latex2e writer] section. The "[latex2e writer]" section of configuration files is processed before the "[xetex writer]" section.

The following settings differ from those of the latex2e writer:

font_encoding
  Disabled (Use Unicode-encoded fonts).
latex_preamble

  > Default: Font setup for Linux Libertine,:

  >     % Linux Libertine (free, wide coverage, not only for Linux)
  >     \setmainfont{Linux Libertine O}
  >     \setsansfont{Linux Biolinum O}
  >     \setmonofont[HyphenChar=None]{DejaVu Sans Mono}

  The optional argument `HyphenChar=None` to the monospace font prevents word hyphenation in literal text.

template
  Default: "xelatex.tex"

### [odf_odt writer]

The following command line options are specific to `odtwriter`:

#### stylesheet

Specify a stylesheet URL, used verbatim.

Default: writers/odf_odt/styles.odt in the installation directory.

#### odf-config-file

Specify a configuration/mapping file relative to the current working directory for additional ODF options. In particular, this file may contain a section named "Formats" that maps default style names to names to be used in the resulting output file allowing for adhering to external standards. For more info and the format of the configuration/mapping file, see the Odt Writer for Docutils document.

#### cloak-email-addresses

Obfuscate email addresses to confuse harvesters while still keeping email links usable with standards-compliant browsers.

#### no-cloak-email-addresses

Do not obfuscate email addresses.

#### table-border-thickness

Specify the thickness of table borders in thousands of a cm. Default is 35.

#### add-syntax-highlighting

Add syntax highlighting in literal code blocks.

#### no-syntax-highlighting

Do not add syntax highlighting in literal code blocks. (default)

#### create-sections

Create sections for headers. (default)

#### no-sections

Do not create sections for headers.

#### create-links

Create links.

#### no-links

Do not create links. (default)

#### endnotes-end-doc

Generate endnotes at end of document, not footnotes at bottom of page.

#### no-endnotes-end-doc

Generate footnotes at bottom of page, not endnotes at end of document. (default)

#### generate-list-toc

Generate a bullet list table of contents, not an ODF/`oowriter` table of contents.

#### generate-oowriter-toc

Generate an ODF/`oowriter` table of contents, not a bullet list. (default) Note: `odtwriter` is not able to determine page numbers, so you will need to open the generated document in `oowriter`, then right-click on the table of contents and select "Update" to insert page numbers.

#### custom-odt-header

Specify the contents of a custom header line. For details about custom headers and about special field character sequences, see section "Custom header/footers: inserting page numbers, date, time, etc" in the Odt Writer for Docutils document for details.

#### custom-odt-footer

Specify the contents of a custom footer line. For details about custom footers and about special field character sequences, see section "Custom header/footers: inserting page numbers, date, time, etc" in the Odt Writer for Docutils document for details.

### [pseudoxml writer]

This writer does not define specific settings.

## [applications]

### [buildhtml application]

#### ignore

List of wildcard (shell globing) patterns, specifying files to silently ignore. To specify multiple patterns, use colon-separated patterns (in configuration files or on the command line); on the command line, the option may also be used more than once.

Default: none. Options: `--ignore`.

#### prune

List of directories not to process. To specify multiple directories, use colon-separated paths (in configuration files or on the command line); on the command line, the option may also be used more than once.

Default: ['.hg', '.bzr', '.git', '.svn', 'CVS']. Options: `--prune`.

#### recurse

Recursively scan subdirectories, or ignore subdirectories.

Default: recurse (1). Options: `--recurse, --local`.

#### silent

Work silently (no progress messages). Independent of "report_level".

Default: show progress (None). Options: `--silent`.

### [docfactory application]

(To be completed.)

## Other Settings

### Command-Line Only

These settings are only effective as command-line options; setting them in configuration files has no effect.

#### config

Path to a configuration file to read (if it exists). [2] Settings may override defaults and earlier settings. The config file is processed immediately. Multiple `--config` options may be specified; each will be processed in turn.

Filesystem path settings contained within the config file will be interpreted relative to the config file's location (not relative to the current working directory).

Default: None. Options: `--config`.

### Internal Settings

These settings are for internal use only; setting them in configuration files has no effect, and there are no corresponding command-line options.

#### _config_files

List of paths of applied configuration files.

Default: None. No command-line options.

#### _directories

(`buildhtml.py` front end.) List of paths to source directories, set from positional arguments.

Default: current working directory (None). No command-line options.

#### _disable_config

Prevent standard configuration files from being read. For programmatic use only.

Default: config files enabled (None). No command-line options.

#### _destination

Path to output destination, set from positional arguments.

Default: stdout (None). No command-line options.

#### _source

Path to input source, set from positional arguments.

Default: stdin (None). No command-line options.

[2] | (1, 2, 3, 4, 5) Path relative to the working directory of the process at launch.

[3] | (1, 2, 3, 4, 5, 6, 7, 8) The overridden setting will automatically be set to `None` for command-line options and config file settings. Client programs which specify defaults that override other settings must do the overriding explicitly, by assigning `None` to the other settings.

[4] | Images are only added to the dependency list if the reStructuredText parser extracted image dimensions from the file.

[5] | (1, 2) The footnote space is trimmed if the reference style is "superscript", and it is left if the reference style is "brackets". The overriding only happens if the parser supports the trim_footnote_reference_space option.

# Old-Format Configuration Files

Formerly, Docutils configuration files contained a single "[options]" section only. This was found to be inflexible, and in August 2003 Docutils adopted the current component-based configuration file sections as described above. Docutils will still recognize the old "[options]" section, but complains with a deprecation warning.

To convert existing config files, the easiest way is to change the section title: change "[options]" to "[general]". Most settings haven't changed. The only ones to watch out for are these:

Old-Format Setting | New Section & Setting
--- | ---
pep_stylesheet | [pep_html writer] stylesheet
pep_stylesheet_path | [pep_html writer] stylesheet_path
pep_template | [pep_html writer] template