David Goodger
Configuration file settings override the built-in defaults, and command-line options override all. Some settings override also an associated setting; [12] others append values from the various sources. [13]
For the technicalities, see Docutils Runtime Settings.
Configuration FilesConfiguration 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:
/etc/docutils.conf: This is a system-wide configuration file, applicable to all Docutils processing on the system.
./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).
~/.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. [13] 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 SyntaxConfiguration 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", "yes", "on", "1"
"false", "no", "off", "0", "" (no value)
Lists are specified either comma- or colon-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
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.
This is from 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: [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.cssConfiguration 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).
Important
Any setting may be specified in any section, but only settings from "active sections" will be used.
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:
[parsers], parser dependencies, and the section specific to the Parser used ("[... parser]").
[readers], reader dependencies, and the section specific to the Reader used ("[... reader]"). For example, [pep reader] depends on [standalone reader].
[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].
[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.
[general]Settings in the "[general]" section are always applied.
auto_id_prefixPrefix 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).
"%" (changed from "id" in Docutils 0.18).
--auto-id-prefix (hidden, intended mainly for programmatic use).
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:
None.
--date, -d, --time, -t, --no-datestamp.
Report debug-level system messages.
Default: None (disabled). Options: --debug, --no-debug.
dump_internalsAt 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_xmlAt 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_settingsAt the end of processing, write all Docutils settings to stderr.
Default: None (disabled). Option: --dump-settings (hidden, for development use only).
dump_transformsAt 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_encodingThe text encoding [14] for error output.
The encoding reported by sys.stderr, locale encoding, or "ascii".
--error-encoding, -e (deprecated).
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.
The error handler may also be appended to the error_encoding setting, delimited by a colon, e.g. --error-encoding=ascii:replace.
"backslashreplace"
--error-encoding-error-handler (hidden, intended mainly for programmatic use).
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_internalsList of internal attributes (colon-separated) to expose as external attributes (with "internal:" namespace prefix). Values are appended. [13]
Default: empty list. Option: --expose-internal-attribute (hidden, for development use only).
generatorInclude a "Generated by Docutils" credit and link in the document footer.
None (disabled).
--generator, -g, --no-generator.
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.
4 (severe).
--halt, --strict (same as --halt=info).
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.
"" (no prefix).
--id-prefix (hidden, intended mainly for programmatic use).
The text encoding [14] for input.
utf-8 (changed from None (auto-detect) in Docutils 0.22).
--input-encoding (shortcut -i removed in Docutils 0.22).
The error handler for undecodable characters in the input. Acceptable values are the Error Handlers of Python's "codecs" module, including:
Raise an exception in case of an encoding error.
Replace malformed data with the official Unicode replacement character, U+FFFD.
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.
"strict".
--input-encoding-error-handler (hidden, intended mainly for programmatic use).
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_pathOutput file path or "-" for stdout.
Caution!
An existing file will be overwritten without warning!
Obsoletes the second positional argument and the internal _destination setting (cf. Future changes in the RELEASE-NOTES).
None (write to stdout).
--output-path, --output.
New in Docutils 0.20. Renamed from "output" to "output_path" in Docutils 0.22.
output_encodingThe text encoding [14] 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.
Note
The "output_encoding" setting may affect the content of the output (e.g. an encoding declaration in HTML or XML or the representation of characters as LaTeX macro vs. literal character).
Docutils may introduce non-ASCII text if you use auto-symbol footnotes. In non-English documents, also auto-generated labels may contain non-ASCII characters.
This setting is ignored by the ODF/ODT Writer which always uses UTF-8.
"utf-8".
--output-encoding (shortcut -o removed in Docutils 0.22).
The error handler for unencodable characters in the output. Acceptable values are the Error Handlers of Python's "codecs" module, including:
Raise an exception in case of an encoding error.
Replace malformed data with a suitable replacement marker, such as "?".
Ignore malformed data and continue without further notice.
Replace with the appropriate XML character reference, such as "†".
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.
"strict".
--output-encoding-error-handler (hidden, intended mainly for programmatic use).
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_levelReport system messages at or higher than the given severity level:
1 info, 2 warning, 3 error, 4 severe, 5 none
See also halt_level.
2 (warning).
--report, -r (with level as number or name)
--verbose, -v (same as --report=1)
--quiet, -q (same as --report=5)
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.
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.
"" (empty string).
--root-prefix.
New in Docutils 0.21.
sectnum_xformEnable 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).
True.
--section-numbering, --no-section-numbering.
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.
None (disabled).
--source-link, -s, --no-source-link.
An explicit URL for a "View document source" link, used verbatim.
None (compute from source_link).
--source-url, --no-source-link.
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.
None (disabled).
--strict-visitor (hidden, for development use only).
List of "classes" attribute values (comma-separated) that will be removed from all elements in the document tree. Values are appended. [13]
Allows eliding class values that interfere with, e.g, CSS rules from 3rd party tools/frameworks.
Warning
Some standard class values are required in order to achieve the expected output rendering; use with caution.
Default: empty list. Option: --strip-class.
strip_elements_with_classesList of "classes" attribute values (comma-separated). Values are appended. [13] Matching elements are removed from the document tree (by the StripClassesAndElements transform).
Warning
Potentially dangerous: may lead to an invalid document tree and subsequent writer errors. Use with caution. It is recommended to validate the document.
Default: empty list. Option: --strip-elements-with-class.
titleThe 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.
None (the displayed document title).
--title.
Enable backlinks from section titles to table of contents entries ("entry"), to the top of the ToC ("top"), or disable (False).
"entry".
--toc-entry-backlinks, --toc-top-backlinks, --no-toc-backlinks.
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.
None (disabled). [2]
--traceback, --no-traceback.
Path [15] to a file for the output of system messages (warnings).
Default: None (stderr). Option: --warnings.
[parsers]Generic parser options:
file_insertion_enabledEnable 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.)
True.
--file-insertion-enabled, --no-file-insertion.
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_enabledEnable 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.
validateValidate 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] character_level_inline_markupRelax 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 languages 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 characters in URLs, names and formulas must be escaped to prevent recognition and possible errors.
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
False.
--character-level-inline-markup, --word-level-inline-markup.
New in Docutils 0.13.
pep_referencesRecognize and link to standalone PEP references (like "PEP 258").
None (disabled); True in the PEP Reader.
--pep-references.
Base URL for PEP references.
Default: "https://peps.python.org/". Option: --pep-base-url.
pep_file_url_templateTemplate for PEP file part of URL, interpolated with the PEP number and appended to pep_base_url.
Default: "pep-%04d". Option: --pep-file-url.
rfc_referencesRecognize and link to standalone RFC references (like "RFC 822").
None (disabled); True in the PEP Reader.
--rfc-references.
Base URL for RFC references.
Default: "https://tools.ietf.org/html/". Option: --rfc-base-url.
smart_quotesActivate 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:
Use smart quotes?
Use alternative quote set (if defined for the language).
Default: None (disabled). Option: --smart-quotes.
smartquotes_localesList with language tag and a string of four typographical quote characters (primary open/close, secondary open/close) for use by the SmartQuotes transform. Values are appended. [13]
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 [3]:
smartquote-locales: nl: ââââ,
fr: « : »:â¹Â : âº
SmartQuotes' pre-defined quote sets.
--smartquotes-locales.
New in Docutils 0.14.
syntax_highlightToken type names used by Pygments when parsing contents of the "code" directive and role.
Supported values:
Use hierarchy of long token type names.
Use short token type names. (For use with Pygments-generated stylesheets.)
No code parsing. Use this to avoid the "Pygments not found" warning when Pygments is not installed.
Default: "long". Option: --syntax-highlight.
tab_widthNumber of spaces for hard tab expansion.
Default: 8. Option: --tab-width.
[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.
Deprecated
Depends on deprecated 3rd-party package recommonmark. Support will be removed in Docutils 1.0.
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
Parser Specific DefaultsFalse.
True.
Enable the DocInfo transform for bibliographic fields.
Default: True. Options: --no-doc-info.
doctitle_xformEnable the promotion of a lone top-level section title to the document title (and subsequent section title to document subtitle) by the DocTitle transform.
Default: True. Options: --no-doc-title.
sectsubtitle_xformEnable the promotion of the title of a lone subsection to a subtitle by the SectSubTitle transform.
False.
--section-subtitles, --no-section-subtitles.
True
True
Generate XML with a DOCTYPE declaration.
Default: True. Options: --no-doctype.
indentsGenerate XML with indents and newlines.
Default: None (disabled). Options: --indents.
newlinesGenerate XML with newlines before and after block-level tags.
Default: None (disabled). Options: --newlines.
xml_declarationGenerate XML with an XML declaration. See also xml_declaration [html writers].
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 XML.
Default: True. Option: --no-xml-declaration.
[html writers]Common settings for the Docutils HTML writers.
attributionFormat for block quote attributions: one of "dash" (em-dash prefix), "parentheses"/"parens", or "none". See also attribution [latex writers].
Default: "dash". Option: --attribution.
cloak_email_addressesScramble 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%40example.org"> abc<span>@</span>example<span>.</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: None (disabled). Option: --cloak-email-addresses.
compact_listsRemove 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" sub-list only). With the "html5" writer, the setting can be overridden for individual lists using the "class" directive (values "compact" and "open").
True.
--compact-lists, --no-compact-lists.
Remove extra vertical whitespace between items of field lists that are "simple" (i.e., all field bodies each contain at most one paragraph). With the "html5" writer, the setting can be overridden for individual lists using the "class" directive (values "compact" and "open").
True.
--compact-field-lists, --no-compact-field-lists.
Embed stylesheet(s) in the HTML output. The stylesheet files must be specified by the stylesheet_path setting and must be accessible during processing. See also embed_stylesheet [latex writers].
True.
--embed-stylesheet, --link-stylesheet.
The format of mathematical content ("math" directive and role) in the output document. Supported values are (case insensitive):
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).
Embed math content as presentational MathML.
Self-contained documents (no JavaScript, no external downloads). MathML is part of the HTML5 standard [5] and supported by all major browsers (since January 2023 also by Chrome).
Docutil's latex2mathml converter supports a considerable subset of LaTeX math syntax.
An external converter can be appended after whitespace, e.g., --math-output="MathML blahtexml":
Fast conversion, support for many symbols and environments, but no "align" (or other equation-aligning) environment. (C++)
Comprehensive macro support but very slow. (Perl)
No "matrix", "align" and "cases" environments. Support may be removed.
Comprehensive macro support, fast, but a large install size. (Haskell)
Format math for display with MathJax, a JavaScript-based math rendering engine.
Works across multiple browsers and platforms. Large set of supported LaTeX math commands and constructs
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 attacks!
Example: MathJax getting started documentation uses:
math-output: mathjax https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
See https://www.jsdelivr.com/ 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.
Include literal LaTeX code.
The failsafe fallback.
writer dependent (see [html4css1 writer], [html5 writer]).
--math-output.
List of CSS stylesheet URLs (comma-separated). Used verbatim.
Overrides also stylesheet_path. [12] See also stylesheet [latex writers].
Default: empty list. Option: --stylesheet.
stylesheet_dirsList of directories where stylesheets can be found (comma-separated). Used by the stylesheet_path setting when resolving relative path arguments.
See also stylesheet_dirs [latex writers].
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.
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.
--stylesheet-dirs.
List of paths to CSS stylesheets (comma-separated). 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_path (if specified) or the current work directory.
See also stylesheet_path [latex writers].
Overrides also stylesheet. [12] Pass an empty string (to either "stylesheet" or "stylesheet_path") to deactivate stylesheet inclusion.
writer dependent (see [html4css1 writer], [html5 writer], [pep_html writer]).
--stylesheet-path.
Class value(s) assigned to all tables. See also table_style [latex writers].
The default CSS sylesheets define:
no borders around table cells,
align table.
The HTML5 stylesheets also define:
Only lines above and below the table and a thin line after the head.
Place the table caption below the table (new in Docutils 0.17).
In addition, the HTML writers process:
Delegate the determination of table column widths to the back-end (leave out the <colgroup> column specification). Overridden by the "widths" option of the "table" directive.
Write column widths determined from the source to the HTML file. Overridden by the "widths" option of the "table" directive.
Default: "". Option: --table-style.
templatePath [15] to template file, which must be encoded in UTF-8. See also template [latex writers].
"template.txt" in the writer's directory (installed automatically) For the exact machine-specific path, use the --help option).
--template.
Prepend an XML declaration. See also xml_declaration [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 XML tools may be unable to read the generated XHTML.
writer dependent.
--xml-declaration, --no-xml-declaration.
The HTML4/CSS1 Writer generates output that conforms to the XHTMLÂ 1 Transitional specification. It shares all settings defined in the [html writers] configuration section.
Writer Specific Defaults1 (for "<h1>").
"HTML math.css".
"html4css1.css".
True.
The maximum length (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. Option: --field-name-limit.
option_limitThe maximum length (in characters) for one-column 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. Option: --option-limit.
[html5 writer]The HTML5 Writer generates valid XML that is compatible with HTML5. It shares all settings defined in the [html writers] configuration section.
New in Docutils 0.13.
Writer Specific Defaults2 (reserve <h1> for the document title). [6]
"MathML" (changed from "HTML math.css"in Docutils 0.22).
"minimal.css, plain.css".
False.
Indicate at which point images should be loaded.
Overridden by the "loading" option of the "image" and "figure" directives.
Supported values:
Embed still images into the HTML document (ignored for videos).
Refer to images in the HTML document (default).
Refer to images. Additionally specify the lazy loading attribute to defer fetching the image.
Default: "link". Option: --image-loading.
New in Docutils 0.18.
section_self_linkAppend an empty anchor element with a href to the section to section headings. See responsive.css for an example how this can be styled to show a symbol allowing users to copy the section's URL.
False.
--section-self-link, --no-section-self-link.
New in Docutils 0.18.
[pep_html writer]The PEP/HTML Writer derives from the HTML4/CSS1 Writer, and shares all settings defined in the [html writers] and [html4css1 writer] configuration sections.
Writer Specific Defaults1 (for "<h1>").
"pep.css".
docutils/writers/pep_html/template.txt in the installation directory. For the exact machine-specific path, use the --help option.
Do not use a random banner image. Mainly used to get predictable results when testing.
Default: None (use random banner). Options: --no-random (hidden).
pep_homeHome URL prefix for PEPs.
Default: "." (current directory). Option: --pep-home.
python_homePython's home URL.
Default: "https://www.python.org". Option: --python-home.
[s5_html writer]The S5/HTML Writer derives from the HTML4/CSS1 Writer, and shares all settings defined in the [html writers] and [html4css1 writer] configuration sections.
Writer Specific Defaultsdisable compact lists.
docutils/writers/s5_html/template.txt in the installation directory. For the exact machine-specific path, use the --help option.
Auto-hide the presentation controls in slideshow mode, or keep them visible at all times.
True (auto-hide).
--hidden-controls, --visible-controls.
Enable or disable the current slide indicator ("1/15").
None (disabled).
--current-slide, --no-current-slide.
Allow or prevent the overwriting of existing theme files in the ui/<theme> directory. This has no effect if "theme_url" is used.
None (keep existing theme files).
--keep-theme-files, --overwrite-theme-files.
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. Overrides also theme_url. [12]
Default: "default". Option: --theme.
theme_urlThe URL of an S5 theme directory. The destination file (output HTML) will link to this theme; nothing will be copied. Overrides also theme. [12]
Default: None. Option: --theme-url.
view_modeThe initial view mode, either "slideshow" or "outline".
Default: "slidewhow". Option: --view-mode.
[latex writers]Common settings for the LaTeX writers [latex2e writer] and [xetex writer].
attributionFormat for block quote attributions: one of "dash" (em-dash prefix), "parentheses"/"parens", or "none". See also attribution [html writers].
Default: "dash". Option: --attribution.
compound_enumeratorsEnable or disable compound enumerators for nested enumerated lists (e.g. "1.2.a.ii").
None (disabled).
--compound-enumerators, --no-compound-enumerators.
Specify LaTeX documentclass.
Default: "article". Option: --documentclass.
documentoptionsSpecify document options. Multiple options can be given, separated by commas.
Default: "a4paper". Option: --documentoptions.
embed_stylesheetEmbed 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). See also embed_stylesheet [html writers].
False (link to stylesheet).
--embed-stylesheet, --link-stylesheet.
LaTeX graphicx package option.
Possible values are "dvips", "pdftex", "dvipdfmx".
Default: "". Option: --graphicx-option.
hyperlink_colorColor of any hyperlinks embedded in text.
Special values:
disables coloring of links (links will be marked by red boxes that are not printed).
results in âinvisibleâ links.
Set hyperref_options to "draft" to completely disable hyperlinking.
Default: "blue". Option: --hyperlink-color.
hyperref_optionsOptions for the hyperref TeX package.
If hyperlink_color is not "false", the expansion of
'colorlinks=true,linkcolor=%s,urlcolor=%s' % (
hyperlink_color, hyperlink_color)
is prepended.
Default: "". Option: --hyperref-options.
latex_preambleLaTeX 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.
writer dependent (see [latex2e writer], [xetex writer]).
--latex-preamble.
Use legacy functions \DUtitle and \DUadmonition with a comma-separated list of class values as optional argument. If False, class values are handled with wrappers and admonitions use the DUadmonition environment. See Generating LaTeX with Docutils for details.
False (default changed in Docutils 0.18).
--legacy-class-functions, --new-class-functions.
New in Docutils 0.17
legacy_column_widthsUse "legacy algorithm" to determine table column widths (for backwards compatibility).
The new algorithm limits the table width to the text width or specified table width and keeps the ratio of specified column widths.
Custom table and/or column widths can be set with the respective options of the "table" directive. See also Generating LaTeX with Docutils.
True (will change to False in Docutils 1.0).
--legacy-column-widths, --new-column-widths.
New in Docutils 0.18.
literal_block_envEnvironment for literal blocks. Used when the block does not contain inline elements. [7]
The values "lstlisting", "listing", "verbatim", "Verbatim", and "verbatimtab" work out of the box; required LaTeX package are automatically loaded.
"" (use "alltt" with quoting of whitespace and special chars).
--literal-block-env.
Per default the LaTeX writer uses \hyperref for hyperlink references to internal or implicit targets. Specify an alternative reference command name, e.g., "ref" or "pageref" to get the section number or the page number as reference text.
Caution!
Drops the original reference text.
Experimental. Not sufficiently tested.
Fails, e.g., with section numbering by Docutils (cf. sectnum_xform) or tables without caption.
Provisional
To be replaced by a dedicated interpreted text role for references (cf. TODO).
Default: "" (use \hyperref). Option: --reference-label.
section_enumerator_separatorThe separator between section number prefix and enumerator for compound enumerated lists (see compound_enumerators).
Generally it isn't recommended to use both, numbered 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.
section_prefix_for_enumeratorsEnable or disable section ("." subsection ...) prefixes for compound enumerators. This has no effect unless compound_enumerators are enabled.
None (disabled).
--section-prefix-for-enumerators, --no-section-prefix-for-enumerators.
Comma-separated list of style files (LaTeX packages). Used verbatim (under Windows, path separators are normalized to forward slashes). Overrides also stylesheet_path. [12] See also stylesheet [html writers].
If embed_stylesheet is False (default), the stylesheet files are referenced with \usepackage (values with extension .sty or no extension) or \input (any other extension). LaTeX will search the specified files in the TeX input path.
Some values change the behaviour of the LaTeX writer:
If the "docutils" package is listed, fallback definitions for Docutils specific LaTeX macros are loaded from there instead of literal inclusion in the output document.
If the "svg" package is listed, SVG images are included with the \includesvg command instead of the default \includegraphics (new in Docutils 0.22).
Default: empty list. Option: --stylesheet.
stylesheet_dirsList of directories where stylesheets can be found (comma-separated). 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.
the working directory of the process at launch.
--stylesheet-dirs.
List of style files (comma-separated). 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_path (if specified) or the current work directory. Overrides also stylesheet. [12] See also stylesheet_path [html writers].
For files in the TeX input path, the stylesheet option is recommended.
Default: empty list. Option: --stylesheet-path.
table_styleSpecify the default style for tables. See also table_style [html writers].
Supported values: "booktabs", "borderless", "colwidths-auto", and "standard". See Generating LaTeX with Docutils for details.
Default: "standard". Option: --table-style.
templatePath [15] to a template file, which must be encoded in UTF-8. See also template [html writers].
Relative paths are searched in the working directory and the "latex2e" writer directory. Docutils provides the template files default.tex, titlepage.tex, titlingpage.tex, and xelatex.tex. The output document is generated from the template by substituting placeholders with the corresponding parts using string.Template.substitute().
writer dependent (see [latex2e writer], [xetex writer]).
--template.
List of style and database(s) for the experimental BibTeX support (comma-separated). Example:
--use-bibtex=unsrt,mydb1,mydb2
Provisional
Name, values, and behaviour may change in future versions or the option may be removed.
Default: empty list (don't use BibTeX). Option --use-bibtex.
use_latex_abstractUse LaTeX abstract environment for the document's abstract.
Default: False. Options: --use-latex-abstract, --topic-abstract.
use_latex_citationsUse \cite for citations.
False (use simulation with figure-floats). The default will change in Docutils 1.0.
--use-latex-citations, --figure-citations.
Attach the content of the bibliographic fields "Author", "Authors", "Address", "Contact", "Organization", and "Date" to the document title.
False (keep date and author info in the document info table).
--use-latex-docinfo, --use-docutils-docinfo.
Let LaTeX generate the table of contents. Generates a ToC with page numbers. Usually LaTeX must be run twice to get the numbers correct.
Default: True. Options: --use-latex-toc, --use-docutils-toc.
use_part_sectionAdd parts on top of the section hierarchy.
Default: False. Option: --use-part-section.
[latex2e writer]The LaTeX2e writer generates a LaTeX source suited for compilation with 8-bit LaTeX (pdfTeX). It shares all settings defined in the [latex writers] configuration section.
Writer Specific DefaultsLoad the "PDF standard fonts" (Times, Helvetica, Courier):
\usepackage{mathptmx} % Times
\usepackage[scaled=.90]{helvet}
\usepackage{courier}
String with LaTeX font encoding. Multiple encodings can be specified separated by commas. The last value becomes the document default.
Default: "T1". Option: --font-encoding.
[xetex writer]The XeTeX writer generates a LaTeX source suited for compilation with XeTeX or LuaTeX. It derives from the latex2e writer, and shares all settings defined in the [latex writers] configuration section.
Writer Specific DefaultsFont 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.
The manpage writer generates documents in the roff markup language for processing into UNIX manual pages with, e.g., mandoc or groff.
text_referencesUse a text rendering instead of the macros UR and MT for reference targets (URI references and email addresses). Some systems (e.g. Solaris troff) do not support these macros. Text references also prevent problems when groff is used on a terminal emulator that does not support OSC8 sequences (alternatively, call groff with the option -rU0).
True (will change to False in Docutils 1.0).
--macro-references, --text-references.
The ODF/ODT Writer generates documents in the OpenDocument Text format (.odt).
The output_encoding setting is ignored, the output encoding is always "UTF-8".
add-syntax_highlightingAdd syntax highlighting in literal code blocks. See section "Syntax highlighting" in the ODT Writer documentation for details.
False.
--add-syntax-highlighting, --no-syntax-highlighting.
Create links.
Default: False. Options: --create-links, --no-links.
create_sectionsCreate sections for headers.
True.
--create-sections, --no-sections.
Obfuscate email addresses to confuse harvesters while still keeping email links usable with standards-compliant browsers.
False.
--cloak-email-addresses, --no-cloak-email-addresses.
Generate endnotes at end of document, not footnotes at bottom of page.
False.
--endnotes-end-doc, --no-endnotes-end-doc.
Generate a native ODF table of contents, not a bullet list. See section "Table of contents" in the ODT Writer documentation for details.
True.
--generate-oowriter-toc, --generate-list-toc.
Path [15] to a configuration/mapping file for additional ODF options. In particular, this file may contain a mapping of default style names to names used in the resulting output file. See section How to use custom style names in the ODT Writer documentation for details.
Default: None. Option: --odf-config-file.
stylesheetPath [15] to a style file. See section Styles and Classes in the ODT Writer documentation for details.
"writers/odf_odt/styles.odt" in the installation directory.
--stylesheet.
Specify the thickness of table borders in thousands of a centimetre. The Table styles section in the ODT Writer documentation describes alternatives for additional customisation of the table style.
Default: 35 (0.35Â mm). Option: --table-border-thickness.
[pseudoxml writer] detailedPretty-print <#text> nodes.
Default: False. Option: --detailed.
[applications]The following applications (front-end tools) provide additional settings.
[buildhtml application]buildhtml.py generates HTML documents from reStructuredText source files in a set of directories and their subdirectories. All visited directories are scanned for "docutils.conf" files which are parsed after the standard configuration files. Path settings [15] in these files are resolved relative to the respective directory.
The output_path setting is ignored.
dry_runDo not process files, show files that would be processed.
Default: False (process files). Option: --dry-run.
ignoreList of glob-style patterns [9] (colon-separated). Source files with matching filename are silently ignored. Values are appended. [13]
Default: empty list. Option: --ignore.
pruneList of glob-style patterns [9] (colon-separated). Matching directories are skipped. Values are appended. [13]
Patterns are expanded similar to path settings [15] and matched against the absolute path of to-be-processed directories. Example: a directory is pruned if it contains a "docutils.conf" file with the lines
[buildhtml application] prune: '.'
The default patterns skip auxiliary directories from Python or popular version control tools anywhere [8].
/*/.hg:/*/.bzr:/*/.git:/*/.svn:/*/.venv:/*/__pycache__.
--prune.
Recursively scan subdirectories.
Default: True. Options: --recurse, --local.
sourcesList of glob-style [9] patterns (colon-separated). Files with matching filename are treated as source documents. Values in configuration files overwrite the default and are overwritten by the command line option.
Default: *.rst:*.rst. Option: --rst-sources.
New in Docutils 0.21.
silentWork silently (no progress messages). Independent of report_level.
Default: None (show progress). Option: --silent.
writerHTML writer version. One of "html", "html4", "html5".
"html" (use Docutils' default HTML writer).
--writer
New in 0.17. Obsoletes the html_writer option.
[docutils application]Docutils' generic front end tool allows combining "reader", "parser", and "writer" components from the Docutils package or 3rd party plug-ins.
New in 0.17. Config file support added in 0.18.
Renamed in 0.19 (the old section name "docutils-cli application" is kept as alias).
Support for reader/parser import names added in 0.19.
readerReader component name. One of "standalone", "pep", or the import name of a plug-in reader module.
Default: "standalone". Option: --reader
parserParser component name. Either "rst", "xml", or the import name of a plug-in parser module. [10]
Default: "rst". Option: --parser
writerWriter component name. One of "html", "html4", "html5", "latex", "xelatex", "odt", "xml", "pseudoxml", "manpage", "pep_html", "s5", an alias, or the import name of a plug-in writer module.
Default: "html5". Option: --writer
Other Settings Command-Line OnlyThese settings are only effective as command-line options; setting them in configuration files has no effect.
configPath to an additional configuration file. The file is processed immediately (if it exists) with settings overriding defaults and earlier settings. [11]
Filesystem path settings [15] contained within the config file will be interpreted relative to the config file's location (not relative to the current working directory).
Multiple --config options may be specified; each will be processed in turn. [11]
Default: None. Option: --config.
Internal SettingsThese settings are for internal use only; setting them in configuration files has no effect, and there are no corresponding command-line options (except for _destination).
_config_filesList of paths of applied configuration files.
Default: None.
_directoriesOnly with the [buildhtml application].
List of paths to source directories, set from positional arguments.
Default: None (current working directory).
_disable_configPrevent standard configuration files from being read. For command-line use, set the DOCUTILSCONFIG variable.
None (config files enabled).
Path to the output file, set from positional arguments.
Deprecated, obsoleted by the output_path setting. Will be removed in Docutils 2.0 (cf. Future changes in the RELEASE-NOTES).
Default: None (stdout). Option: --output.
_sourcePath to input source, set from positional arguments.
Default: None (stdin).
sectnum_depthStores the value of the "sectnum" directive's "depth" option if sectnum_xform is False.
No default. [16]
sectnum_prefixStores the value of the "sectnum" directive's "prefix" option if sectnum_xform is False.
No default. [16]
sectnum_startStores the value of the "sectnum" directive's "start" option if sectnum_xform is False.
No default. [16]
sectnum_suffixStores the value of the "sectnum" directive's "suffix" option if sectnum_xform is False.
No default. [16]
Appendix Old-Format Configuration FilesFormerly, 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. Up to version 2.0, Docutils will still recognize the old "[options]" section, but complain 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
Input Encoding Auto-DetectionUp to Docutils 0.21, the input_encoding default value was None and the actual input encoding detected from a Unicode byte order mark (BOM) or an encoding declaration in the source.
The default input encoding changed to "utf-8" in Docutils 0.22. Currently, auto-detection can be selected with an input_encoding value None (rsp. an empty string in a configuration file). However, this feature is deprecated and will be removed in Docutils 1.0. See the inspecting_codecs package for a replacement.
Encoding DeclarationInput encoding auto-detection scans the source for an encoding declaration inspired by PEP 263:
A comment like
.. text encoding: <encoding name>
on the first or second line defines <encoding name> as the source's input encoding.
Examples: (using formats recognized by popular editors)
.. -*- mode: rst -*- -*- coding: latin1 -*-
or:
.. vim: set fileencoding=cp737 :
More precisely, the first and second line are searched for the following regular expression:
coding[:=]\s*([-\w.]+)
The first group of this expression is then interpreted as encoding name. If the first line matches the second line is ignored.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4