| Author: | David Goodger |
|---|---|
| Contact: | docutils-develop@lists.sourceforge.net |
| Revision: | 9077 |
| Date: | 2022-06-17 |
| Copyright: | This document has been placed in the public domain. |
Contents
Configuration files are used for persistent customization; they can be set once and take effect every time you use a component, e.g., via a front-end tool. Configuration file settings override the built-in defaults, and command-line options override all. For the technicalities, see Docutils Runtime Settings.
By default, Docutils checks the following places for configuration files, in the following order:
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 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 interchangeably 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
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.css
Individual configuration sections and settings are described in the following section.
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:
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.
Settings in the "[general]" section are always applied.
Prefix prepended to all auto-generated identifier keys generated within the document, after id_prefix. Ensure the value conforms to the restrictions on identifiers in the output format, as it is not subjected to the identifier normalization.
A trailing "%" is replaced with the tag name (new in Docutils 0.16).
Default: "%" (changed in 0.18 from "id"). Option: --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().
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:
At the end of processing, write all internal attributes of the document (document.__dict__) to stderr.
Default: don't (None). Option: --dump-internals (hidden, for development use only).
At the end of processing, write the pseudo-XML representation of the document to stderr.
Default: don't (None). Option: --dump-pseudo-xml (hidden, for development use only).
At the end of processing, write all Docutils settings to stderr.
Default: don't (None). Option: --dump-settings (hidden, for development use only).
At the end of processing, write a list of all transforms applied to the document to stderr.
Default: don't (None). Option: --dump-transforms (hidden, for development use only).
The error handler for unencodable characters in error output. Acceptable values are the Error Handlers of Python's "encoding" module. See also output_encoding_error_handler.
Default: "backslashreplace" Options: --error-encoding-error-handler, --error-encoding, -e.
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). Option: --exit-status.
List of internal attributes 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). Option: --expose-internal-attribute (hidden, for development use only).
Enable or disable backlinks from footnotes and citations to their references.
Default: enabled (True). Options: --footnote-backlinks, --no-footnote-backlinks.
Include a "Generated by Docutils" credit and link in the document footer.
Default: off (None). Options: --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.
Default: severe (4). Options: --halt, --strict.
Prefix prepended to all identifier keys generated within the document. Ensure the value conforms to the restrictions on identifiers in the output format, as it is not subjected to the identifier normalization. See also auto_id_prefix.
Default: "" (empty). Option: --id-prefix (hidden, intended mainly for programmatic use).
The text encoding for input.
Default: auto-detect (None). Options: --input-encoding, -i.
The error handler for undecodable characters in the input. Acceptable values are the Error Handlers of Python's "encoding" module, including:
Default: "strict". Options: --input-encoding-error-handler, --input-encoding, -i.
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.
The error handler for unencodable characters in the output. Acceptable values are the Error Handlers of Python's "encoding" module, including:
Default: "strict". Options: --output-encoding-error-handler, --output-encoding, -o.
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]. [4] The format is one path per line with forward slashes as separator, the encoding is UTF-8.
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 UTF-8, replace the cat command with a call to a converter, e.g.:
$(shell iconv -f utf-8 -t latin1 hamdeps.txt)
Default: None. Option: --record-dependencies.
| [1] | Images are only added to the dependency list if they are embedded into the output or the reStructuredText parser extracted image dimensions from the file. |
Report system messages at or higher than <level>:
1 info 2 warning 3 error 4 severe 5 none
See also halt_level.
Default: warning (2). Options: --report, -r, --verbose, -v, --quiet, -q.
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.
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.
An explicit URL for a "View document source" link, used verbatim.
Default: compute if source_link (None). Options: --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.
Default: disabled (None). Option: --strict-visitor (hidden, for development use only).
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.
Enable the removal of comment elements from the document tree.
Default: disabled (None). Options: --strip-comments, --leave-comments.
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.
The document title as metadata which does not become part of the document body. Stored as the document's title attribute. For example, in HTML output the metadata document title appears in the title bar of the browser window.
This setting overrides a displayed document title and is overridden by a "title" directive.
Default: none. Option: --title.
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.
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.
Path to a file for the output of system messages (warnings). [4]
Default: stderr (None). Option: --warnings.
Generic parser options:
Enable or disable directives or directive that insert the contents of external files, such as "include" or "raw" with option "url". 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.
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.
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.
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 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. 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.
Recognize and link to standalone PEP references (like "PEP 258").
Default: disabled (None); enabled (True) in PEP Reader. Option: --pep-references.
Base URL for PEP references.
Default: "https://peps.python.org/". Option: --pep-base-url.
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.
Recognize and link to standalone RFC references (like "RFC 822").
Default: disabled (None); enabled (True) in PEP Reader. Option: --rfc-references.
Base URL for RFC references.
Default: "http://www.faqs.org/rfcs/". Option: --rfc-base-url.
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:
Default: "no". Option: --smart-quotes.
New in Docutils 0.10.
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.)
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.
Token type names used by Pygments when parsing contents of the code directive and role.
Supported values:
Default: "long". Option: --syntax-highlight.
New in Docutils 0.9.
Remove spaces before footnote references?
Default: None [2]
Options: --trim-footnote-reference-space, --leave-footnote-reference-space.
| [2] | Depending on the writer-specific footnote_references setting. The footnote space is trimmed if the reference style is "superscript", and it is left if the reference style is "brackets". |
Provided by the 3rd party package myst-docutils. See MyST with Docutils and its Sphinx configuration options (some settings are not available with Docutils).
Provided by the 3rd party package pycmark. Currently no configuration settings.
Provisional, depends on (deprecated) 3rd-party package recommonmark. Currently no configuration settings.
Enable or disable the bibliographic field list transform (docutils.transforms.frontmatter.DocInfo).
Default: enabled (True). Options: --no-doc-info.
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.
Enable or disable the promotion of the title of a lone subsection to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
Default: disabled (False). Options: --section-subtitles, --no-section-subtitles.
The pep_references and rfc_references settings ([restructuredtext parser]) are set on by default.
Caution!
Generate XML with a DOCTYPE declaration.
Default: do (True). Options: --no-doctype.
Generate XML with newlines before and after tags.
Default: don't (None). Options: --newlines.
Generate XML with an XML declaration. See also xml_declaration [html writers].
Default: do (True). Option: --no-xml-declaration.
Format for block quote attributions: one of "dash" (em-dash prefix), "parentheses"/"parens", or "none". See also attribution [latex writers].
Default: "dash". Option: --attribution.
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%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: don't cloak (None). Option: --cloak-email-addresses.
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" sub-list 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.
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 the stylesheet in the output HTML file. The stylesheet file must specified by the stylesheet_path setting and must be accessible during processing. See also embed_stylesheet [latex writers].
Default: enabled. Options: --embed-stylesheet, --link-stylesheet.
Format for footnote references, one of "superscript" or "brackets". See also footnote_references [latex writers].
Overrides [5] trim_footnote_reference_space, if the parser supports this option.
Default: "brackets". Option: --footnote-references.
The initial level for header elements. This does not affect the document title & subtitle; see doctitle_xform.
Default: writer dependent (see [html4css1 writer], [html5 writer], [pep_html writer]). Option: --initial-header-level.
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.
A URL pointing to a MathJax library should be appended after whitespace. A warning is given if this is missing.
|
| MathML: | Embed math content as presentational MathML.
An external converter can be appended after whitespace, e.g., --math-output="MathML latexml": |
| LaTeX: | Include literal LaTeX code. The failsafe fallback. |
Default: HTML math.css. Option: --math-output.
New in Docutils 0.8.
A comma-separated list of CSS stylesheet URLs, used verbatim. See also stylesheet [latex writers].
Overrides also stylesheet_path. [5]
Default: None. Option: --stylesheet.
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-dirs.
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. See also stylesheet_path [latex writers].
Also overrides "stylesheet". [5] Pass an empty string (to either "stylesheet" or "stylesheet_path") to deactivate stylesheet inclusion.
Default: writer dependent (see [html4css1 writer], [html5 writer], [pep_html writer]). Option: --stylesheet-path.
Class value(s) added to all tables. See also table_style [latex writers].
The default CSS sylesheets define:
- borderless
- No borders around the table.
- align-left, align-center, align-right
- Align the tables
The HTML5 stylesheets also define:
- booktabs
- Only lines above and below the table and a thin line after the head.
- captionbelow
- Place the table caption below the table (New in Docutils 0.17).
In addition, the HTML writers support:
- colwidths-auto
- 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.
- colwidths-grid
- Backwards compatibility setting. Write column widths determined from the source to the HTML file. Overridden by the "widths" option of the table directive.
Default: "". Option: --table-style.
Path to template file, which must be encoded in UTF-8. [4] See also template [latex writers].
Default: "template.txt" in the writer's directory (installed automatically; for the exact machine-specific path, use the --help option). 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.
Default: writer dependent. Options: --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.
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.
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.
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.
Deprecated. Obsoleted by image_loading.
Suggest at which point images should be loaded.
| embed: | If the image can be read from the local file system, the image data is embedded into the HTML document. |
|---|---|
| link: | Link to image in the HTML document (default). |
| lazy: | Link to image. Specify the lazy loading attribute to defer fetching the image. |
Default: "link". Option: --image-loading.
New in Docutils 0.18.
Append 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.
Default: disabled (False). Options: --section-self-link, --no-section-self-link.
New in Docutils 0.18.
The PEP/HTML Writer derives from the HTML4/CSS1 Writer, and shares all settings defined in the [html writers] and [html4css1 writer] configuration sections.
Do not use a random banner image. Mainly used to get predictable results when testing.
Default: random enabled (None). Options: --no-random (hidden).
The S5/HTML Writer derives from the HTML4/CSS1 Writer, and shares all settings defined in the [html writers] and [html4css1 writer] configuration sections.
Enable or disable the current slide indicator ("1/15").
Default: disabled (None). Options: --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.
Default: keep existing theme files (None). Options: --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. Also overrides the "theme_url" setting. [5]
Default: "default". Option: --theme.
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. [5]
Default: None. Option: --theme-url.
The initial view mode, either "slideshow" or "outline".
Default: "slidewhow". Option: --view-mode.
Common settings for the LaTeX writers [latex2e writer] and [xetex writer].
Enable or disable compound enumerators for nested enumerated lists (e.g. "1.2.a.ii").
Default: disabled (None). Options: --compound-enumerators, --no-compound-enumerators.
Specify document options. Multiple options can be given, separated by commas.
Default: "a4paper". Option: --documentoptions.
Use the Docutils-specific macros \DUfootnote and \DUfootnotetext for footnotes.
TODO: The alternative, "use_latex_footnotes" is not implemented yet.
Default: on. Option: --docutils-footnotes.
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). See also embed_stylesheet [html writers].
Default: off. Options: --embed-stylesheet, --link-stylesheet.
Format for footnote references: one of "superscript" or "brackets". See also footnote_references [html writers].
Overrides [5] trim_footnote_reference_space, if the parser supports this option.
Default: "superscript". Option: --footnote-references.
LaTeX graphicx package option.
Possible values are "dvips", "pdftex", "dvipdfmx".
Default: "". Option: --graphicx-option.
Color of any hyperlinks embedded in text.
Set hyperref_options to "draft" to completely disable hyperlinking.
Default: "blue". Option: --hyperlink-color.
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.
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: writer dependent (see [latex2e writer], [xetex writer]). Option: --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.
Default: False (changed in Docutils 0.18). Options: --legacy-class-functions, --new-class-functions.
New in Docutils 0.17.
Use "legacy algorithm" or new algorithm to determine table column widths.
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.
Default: True (will change to False in 0.19). Options: --legacy-column-widths, --new-column-widths.
New in Docutils 0.18.
When possible[3], use the specified environment for literal blocks.
Default: "" (quoting of whitespace and special chars). Option: --literal-block-env.
| [3] | A literal-block element may originate from a parsed literal. A LaTeX verbatim environment is only usable it does not contain inline elements. |
Per default the latex-writer puts the reference title into hyper references. Specify "ref*" or "pageref*" to get the section number or the page number.
Default: "" (use hyper references). Option: --reference-label.
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.
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.
A comma-separated list of style files. See also stylesheet [html writers].
Overrides also stylesheet_path. [5]
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.
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-dirs.
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. See also stylesheet_path [html writers].
The stylesheet option is preferred for files in the TeX input path.
Also overrides stylesheet. [5]
Default: no stylesheet (""). Option: --stylesheet-path.
Specify 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.
Path [4] to template file, which must be encoded in UTF-8. See also template [html writers].
Default: writer dependent (see [latex2e writer], [xetex writer]). Option: --template.
Specify style and database for the experimental BibTeX support, for example:
--use-bibtex=mystyle,mydb1,mydb2
Default: "" (don't use BibTeX). Option --use-bibtex.
Use LaTeX abstract environment for the document's abstract.
Default: off. Options: --use-latex-abstract, --topic-abstract.
Use cite for citations instead of a simulation with figure-floats.
Default: off. Options: --use-latex-citations, --figure-citations.
Attach author and date to the document title instead of the bibliographic fields.
Default: off. Options: --use-latex-docinfo, --use-docutils-docinfo.
To get page numbers 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.
Add parts on top of the section hierarchy.
Default: don't (None). Option: --use-part-section.
The LaTeX2e writer generates a LaTeX source for compilation with 8-bit LaTeX (pdfTeX). It shares all settings defined in the [latex writers] configuration section.
Load the "PDF standard fonts" (Times, Helvetica, Courier):
\usepackage{mathptmx} % Times
\usepackage[scaled=.90]{helvet}
\usepackage{courier}
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.
The XeTeX writer generates a LaTeX source for compilation with XeTeX or LuaTeX. It derives from the latex2e writer, and shares all settings defined in the [latex writers] and [latex2e writer] configuration sections.
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.
The following command line options are specific to odtwriter:
Specify a stylesheet URL, used verbatim.
Default: writers/odf_odt/styles.odt in the installation directory.
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.
Obfuscate email addresses to confuse harvesters while still keeping email links usable with standards-compliant browsers.
Do not obfuscate email addresses.
Specify the thickness of table borders in thousands of a cm. Default is 35.
Add syntax highlighting in literal code blocks.
Do not add syntax highlighting in literal code blocks. (default)
Create sections for headers. (default)
Do not create sections for headers.
Create links.
Do not create links. (default)
Generate endnotes at end of document, not footnotes at bottom of page.
Generate footnotes at bottom of page, not endnotes at end of document. (default)
Generate a bullet list table of contents, not an ODF/oowriter table of contents.
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.
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.
Do not process files, show files that would be processed.
Default: False. Option: --dry-run.
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. Option: --ignore.
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']. Option: --prune.
Recursively scan subdirectories, or ignore subdirectories.
Default: recurse (True). Options: --recurse, --local.
Work silently (no progress messages). Independent of "report_level".
Default: show progress (None). Option: --silent.
HTML writer version. One of "html", "html4", "html5".
Default: "html" (use Docutils' default HTML writer). Option: --writer
New in 0.17. Obsoletes the html_writer option.
New in 0.17. Config file support added in 0.18. Renamed in 0.19 (the old name "docutils-cli application" is kept as alias). Support for reader/parser import names added in 0.19.
Reader component name. One of "standalone", "pep", or the import name of a drop-in reader module.
Default: "standalone". Option: --reader
Parser component name. Either "rst" (default) or the import name of a drop-in parser module.
Parsers for CommonMark known to work with Docutils include "pycmark", "myst", and "recommonmark".
Default: "rst". Option: --parser
Writer component name. One of "html", "html4", "html5", "latex", "xelatex", "odt", "xml", "pseudoxml", "manpage", "pep_html", "s5", an alias, or the import name of a drop-in writer module.
Default: "html5". Option: --writer
These settings are only effective as command-line options; setting them in configuration files has no effect.
Path to a configuration file to read (if it exists). [4] 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. Option: --config.
These settings are for internal use only; setting them in configuration files has no effect, and there are no corresponding command-line options.
(buildhtml.py front end.) List of paths to source directories, set from positional arguments.
Default: current working directory (None). No command-line options.
Prevent standard configuration files from being read. For programmatic use only.
Default: config files enabled (None). No command-line options.
Path to output destination, set from positional arguments.
Default: stdout (None). No command-line options.
Path to input source, set from positional arguments.
Default: stdin (None). No command-line options.
| [4] | (1, 2, 3, 4, 5) Path relative to the working directory of the process at launch. |
| [5] | (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. |
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. 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 |