.. include:: ../header.txt ======================== Docutils Configuration ======================== :Author: David Goodger :Contact: docutils-develop@lists.sourceforge.net :Revision: $Revision: 9077 $ :Date: $Date: 2022-06-17 13:31:28 +0200 (Fr, 17. Jun 2022) $ :Copyright: This document has been placed in the public domain. .. sidebar:: Docutils Security for Web Applications For details about securing web applications, please see `Deploying Docutils Securely <../howto/security.html>`_. .. contents:: ------------------- Configuration Files ------------------- Configuration files are used for persistent customization; they can be set once and take effect every time you use a component, e.g., via a `front-end tool`_. 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: 1. ``/etc/docutils.conf``: This is a system-wide configuration file, applicable to all Docutils processing on the system. 2. ``./docutils.conf``: This is a project-specific configuration file, located in the current directory. The Docutils front end has to be executed from the directory containing this configuration file for it to take effect (note that this may have nothing to do with the location of the source files). Settings in the project-specific configuration file will override corresponding settings in the system-wide file. 3. ``~/.docutils``: This is a user-specific configuration file, located in the user's home directory. Settings in this file will override corresponding settings in both the system-wide and project-specific configuration files. If more than one configuration file is found, all will be read but later entries will override earlier ones. For example, a "stylesheet" entry in a user-specific configuration file will override a "stylesheet" entry in the system-wide file. The default implicit config file paths can be overridden by the ``DOCUTILSCONFIG`` environment variable. ``DOCUTILSCONFIG`` should contain a colon-separated (semicolon-separated on Windows) sequence of config file paths to search for; leave it empty to disable implicit config files altogether. Tilde-expansion is performed on paths. Paths are interpreted relative to the current working directory. Empty path items are ignored. In addition, a configuration file may be explicitly specified with the ``--config`` command-line option. This configuration file is read after the three implicit ones listed above (or the ones defined by the ``DOCUTILSCONFIG`` environment variable), and its entries will have priority. .. _Docutils Runtime Settings: ../api/runtime-settings.html ------------------------- Configuration File Syntax ------------------------- Configuration files are UTF-8-encoded text files. The ConfigParser.py_ module from Python_'s standard library is used to read them. From its documentation: The configuration file consists of sections, lead by a "[section]" header and followed by "name: value" entries, with continuations in the style of `RFC 822`_; "name=value" is also accepted. Note that leading whitespace is removed from values. ... Lines beginning with "#" or ";" are ignored and may be used to provide comments. .. Note:: No format string interpolation is done. Configuration file entry names correspond to internal runtime settings. Underscores ("_") and hyphens ("-") can be used 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: List values can be comma- or colon-delimited. strip_classes_, strip_elements_with_classes_, stylesheet, and stylesheet_path use the comma as delimiter, whitespace around list values is stripped. :: strip-classes: ham,eggs, strip-elements-with-classes: sugar, salt, flour stylesheet: html4css1.css, math.css, style with spaces.css stylesheet-path: ../styles/my.css, ../styles/funny.css expose_internals_, ignore_ and prune_ use the colon as delimiter and do not strip whitespace:: expose_internals: b:c:d Example ======= This is 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. ------------------------------------- Configuration File Sections & Entries ------------------------------------- Below are the Docutils runtime settings, listed by config file section. **Any setting may be specified in any section, but only settings from active sections will be used.** Sections correspond to Docutils components (module name or alias; section names are always in lowercase letters). Each `Docutils application`_ uses a specific set of components; corresponding configuration file sections are applied when the application is used. Configuration sections are applied in general-to-specific order, as follows: 1. `[general]`_ 2. `[parsers]`_, parser dependencies, and the section specific to the Parser used ("[... parser]"). 3. `[readers]`_, reader dependencies, and the section specific to the Reader used ("[... reader]"). For example, `[pep reader]`_ depends on `[standalone reader]`_. 4. `[writers]`_, writer family ("[... writers]"; if applicable), writer dependencies, and the section specific to the writer used ("[... writer]"). For example, `[pep_html writer]`_ depends on `[html writers]`_ and `[html4css1 writer]`_. 5. `[applications]`_, application dependencies, and the section specific to the Application (front-end tool) in use ("[... application]"). Since any setting may be specified in any section, this ordering allows component- or application-specific overrides of earlier settings. For example, there may be Reader-specific overrides of general settings; Writer-specific overrides of Parser settings; Application-specific overrides of Writer settings; and so on. If multiple configuration files are applicable, the process is completed (all sections are applied in the order given) for each one before going on to the next. For example, a "[pep_html writer] stylesheet" setting in an earlier configuration file would be overridden by an "[html4css1 writer] stylesheet" setting in a later file. Some knowledge of Python_ is assumed for some attributes. .. _ConfigParser.py: https://docs.python.org/3/library/configparser.html .. _Python: https://www.python.org/ .. _RFC 822: https://www.rfc-editor.org/rfc/rfc822.txt .. _front-end tool: .. _Docutils application: tools.html [general] ========= Settings in the "[general]" section are always applied. auto_id_prefix -------------- Prefix prepended to all auto-generated `identifier keys` generated within the document, after id_prefix_. Ensure the value conforms to the restrictions on identifiers in the output format, as it is not subjected to the `identifier normalization`_. A trailing "%" is replaced with the tag name (new in Docutils 0.16). Default: "%" (changed in 0.18 from "id"). Option: ``--auto-id-prefix`` (hidden, intended mainly for programmatic use). .. _identifier normalization: ../ref/rst/directives.html#identifier-normalization datestamp --------- 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: __ https://docs.python.org/3/library/time.html#time.strftime debug ----- Report debug-level system messages. Default: don't (None). Options: ``--debug, --no-debug``. dump_internals -------------- At the end of processing, write all internal attributes of the document (``document.__dict__``) to stderr. Default: don't (None). Option: ``--dump-internals`` (hidden, for development use only). dump_pseudo_xml --------------- At the end of processing, write the pseudo-XML representation of the document to stderr. Default: don't (None). Option: ``--dump-pseudo-xml`` (hidden, for development use only). dump_settings ------------- At the end of processing, write all Docutils settings to stderr. Default: don't (None). Option: ``--dump-settings`` (hidden, for development use only). dump_transforms --------------- At the end of processing, write a list of all transforms applied to the document to stderr. Default: don't (None). Option: ``--dump-transforms`` (hidden, for development use only). error_encoding -------------- The text encoding for error output. Default: "ascii". Options: ``--error-encoding, -e``. error_encoding_error_handler ---------------------------- The error handler for unencodable characters in error output. 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``. exit_status_level ----------------- A system message level threshold; non-halting system messages at or above this level will produce a non-zero exit status at normal exit. Exit status is the maximum system message level plus 10 (11 for INFO, etc.). Default: disabled (5). Option: ``--exit-status``. expose_internals ---------------- 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). footnote_backlinks ------------------ Enable or disable backlinks from footnotes_ and citations_ to their references. Default: enabled (True). Options: ``--footnote-backlinks, --no-footnote-backlinks``. generator --------- Include a "Generated by Docutils" credit and link in the document footer. Default: off (None). Options: ``--generator, -g, --no-generator``. halt_level ---------- The threshold at or above which system messages are converted to exceptions, halting execution immediately. If `traceback`_ is set, the exception will propagate; otherwise, Docutils will exit. See also report_level_. Default: severe (4). Options: ``--halt, --strict``. id_prefix --------- Prefix prepended to all identifier keys generated within the document. Ensure the value conforms to the restrictions on identifiers in the output format, as it is not subjected to the `identifier normalization`_. See also auto_id_prefix_. Default: "" (empty). Option: ``--id-prefix`` (hidden, intended mainly for programmatic use). input_encoding -------------- The text encoding for input. Default: auto-detect (None). Options: ``--input-encoding, -i``. input_encoding_error_handler ---------------------------- The error handler for undecodable characters in the input. Acceptable values are the `Error Handlers`_ of Python's "encoding" module, including: strict Raise an exception in case of an encoding error. replace Replace malformed data with the official Unicode replacement character, U+FFFD. ignore Ignore malformed data and continue without further notice. Default: "strict". Options: ``--input-encoding-error-handler, --input-encoding, -i``. language_code ------------- Case-insensitive `language tag`_ as defined in `BCP 47`_. Sets the document language, also used for localized directive and role names as well as Docutils-generated text. A typical language identifier consists of a 2-letter language code from `ISO 639`_ (3-letter codes can be used if no 2-letter code exists). The language identifier can have an optional subtag, typically for variations based on country (from `ISO 3166`_ 2-letter country codes). Avoid subtags except where they add useful distinguishing information. Examples of language tags include "fr", "en-GB", "pt-br" (the same as "pt-BR"), and "de-1901" (German with pre-1996 spelling). The language of document parts can be specified with a "language-" `class attribute`_, e.g. ``.. class:: language-el-polyton`` for a quote in polytonic Greek. Default: English ("en"). Options: ``--language, -l``. .. _class attribute: ../ref/doctree.html#classes output_encoding --------------- The text encoding for output. Default: "utf-8". Options: ``--output-encoding, -o``. output_encoding_error_handler ----------------------------- The error handler for unencodable characters in the output. Acceptable values are the `Error Handlers`_ of Python's "encoding" module, including: strict Raise an exception in case of an encoding error. replace Replace malformed data with a suitable replacement marker, such as "?". ignore Ignore malformed data and continue without further notice. xmlcharrefreplace Replace with the appropriate XML character reference, such as "``†``". backslashreplace Replace with backslash escape sequences, such as "``\u2020``". Default: "strict". Options: ``--output-encoding-error-handler, --output-encoding, -o``. record_dependencies ------------------- Path to a file where Docutils will write a list of files that were required to generate the output, e.g. included files or embedded stylesheets [#dependencies]_. [#pwd]_ 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``. .. [#dependencies] 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_level ------------ Report system messages at or higher than : 1 info 2 warning 3 error 4 severe 5 none See also halt_level_. Default: warning (2). Options: ``--report, -r, --verbose, -v, --quiet, -q``. sectnum_xform ------------- Enable or disable automatic section numbering by Docutils (docutils.transforms.parts.SectNum) associated with the `sectnum directive`_. If disabled, section numbers might be added to the output by the renderer (e.g. by LaTeX or via a CSS style definition). Default: enabled (True). Options: ``--section-numbering``, ``--no-section-numbering``. .. _sectnum directive: ../ref/rst/directives.html#sectnum source_link ----------- Include a "View document source" link in the document footer. URL will be relative to the destination. Default: don't (None). Options: ``--source-link, -s, --no-source-link``. source_url ---------- An explicit URL for a "View document source" link, used verbatim. Default: compute if source_link (None). Options: ``--source-url, --no-source-link``. strict_visitor -------------- When processing a document tree with the Visitor pattern, raise an error if a writer does not support a node type listed as optional. For transitional development use. Default: disabled (None). Option: ``--strict-visitor`` (hidden, for development use only). strip_classes ------------- Comma-separated list_ of "classes" attribute values to remove from all elements in the document tree. The command line option may be used more than once. .. WARNING:: Potentially dangerous; use with caution. Default: disabled (None). Option: ``--strip-class``. strip_comments -------------- Enable the removal of comment elements from the document tree. Default: disabled (None). Options: ``--strip-comments``, ``--leave-comments``. strip_elements_with_classes --------------------------- Comma-separated list_ of "classes" attribute values; matching elements are removed from the document tree. The command line option may be used more than once. .. WARNING:: Potentially dangerous; use with caution. Default: disabled (None). Option: ``--strip-element-with-class``. title ----- The `document title` as metadata which does not become part of the document body. 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``. .. _title attribute: ../ref/doctree.html#title-attribute .. _document title: ../ref/rst/restructuredtext.html#document-title .. _"title" directive: ../ref/rst/directives.html#metadata-document-title toc_backlinks ------------- Enable backlinks from section titles to table of contents entries ("entry"), to the top of the TOC ("top"), or disable ("none"). Default: "entry". Options: ``--toc-entry-backlinks, --toc-top-backlinks, --no-toc-backlinks``. traceback --------- Enable Python tracebacks when halt-level system messages and other exceptions occur. Useful for debugging, and essential for issue reports. Exceptions are allowed to propagate, instead of being caught and reported (in a user-friendly way) by Docutils. Default: disabled (None) unless Docutils is run programmatically using the `Publisher Interface`_. Options: ``--traceback, --no-traceback``. .. _Publisher Interface: ../api/publisher.html warning_stream -------------- Path to a file for the output of system messages (warnings). [#pwd]_ Default: stderr (None). Option: ``--warnings``. [parsers] ========= Generic parser options: file_insertion_enabled ---------------------- 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``. .. _include: ../ref/rst/directives.html#include .. _raw: ../ref/rst/directives.html#raw line_length_limit ----------------- Maximal number of characters in an input line or `substitution`_ definition. To prevent extraordinary high processing times or memory usage for certain input constructs, a "warning" system message is inserted instead. Default: 10 000. Option: ``--line-length-limit`` New in Docutils 0.17. .. _substitution: ../ref/rst/directives.html#substitution raw_enabled ----------- Enable or disable the "raw_" directive. A "warning" system message (including the directive text) is inserted instead. See also file_insertion_enabled_ for another security-relevant setting. Default: enabled (True). Options: ``--raw-enabled, --no-raw``. [restructuredtext parser] ------------------------- character_level_inline_markup ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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. pep_references ~~~~~~~~~~~~~~ Recognize and link to standalone PEP references (like "PEP 258"). Default: disabled (None); enabled (True) in PEP Reader. Option: ``--pep-references``. pep_base_url ~~~~~~~~~~~~ Base URL for PEP references. Default: "https://peps.python.org/". Option: ``--pep-base-url``. pep_file_url_template ~~~~~~~~~~~~~~~~~~~~~ Template for PEP file part of URL, interpolated with the PEP number and appended to pep_base_url_. Default: "pep-%04d". Option: ``--pep-file-url``. rfc_references ~~~~~~~~~~~~~~ Recognize and link to standalone RFC references (like "RFC 822"). Default: disabled (None); enabled (True) in PEP Reader. Option: ``--rfc-references``. rfc_base_url ~~~~~~~~~~~~ Base URL for RFC references. Default: "http://www.faqs.org/rfcs/". Option: ``--rfc-base-url``. smart_quotes ~~~~~~~~~~~~ Activate the SmartQuotes_ transform to change straight quotation marks to typographic form. `Quote characters`_ are selected according to the language of the current block element (see language_code_, smartquotes_locales_, and the `pre-defined quote sets`__). Also changes consecutive runs of hyphen-minus and full stops (``---``, ``--``, ``...``) to em-dash, en-dash, and ellipsis Unicode characters respectively. Supported values: booleans_ (yes/no) Use smart quotes? alt (or "alternative") Use alternative quote set (if defined for the language). Default: "no". Option: ``--smart-quotes``. New in Docutils 0.10. .. _SmartQuotes: smartquotes.html __ smartquotes.html#localization .. _quote characters: https://en.wikipedia.org/wiki/Non-English_usage_of_quotation_marks smartquotes_locales ~~~~~~~~~~~~~~~~~~~ Typographical quotes used by the SmartQuotes_ transform. A comma-separated list_ with language tag and a set of four quotes (primary open/close, secondary open/close)smartquotes_locales. (If more than one character shall be used for a quote (e.g. padding in French quotes), a colon-separated list may be used.) Example: Ensure a correct leading apostrophe in ``'s Gravenhage`` in Dutch (at the cost of incorrect opening single quotes) and set French quotes to double and single guillemets with inner padding:: smartquote-locales: nl: „”’’, fr: « : »:‹ : › Default: None. Option: ``--smartquotes-locales``. New in Docutils 0.14. syntax_highlight ~~~~~~~~~~~~~~~~ Token type names used by Pygments_ when parsing contents of the code_ directive and role. Supported values: long Use hierarchy of long token type names. short Use short token type names. (For use with `Pygments-generated stylesheets`_.) none No code parsing. Use this to avoid the "Pygments not found" warning when Pygments is not installed. Default: "long". Option: ``--syntax-highlight``. New in Docutils 0.9. .. _Pygments: https://pygments.org/ .. _code: ../ref/rst/directives.html#code .. _Pygments-generated stylesheets: https://pygments.org/docs/cmdline/#generating-styles tab_width ~~~~~~~~~ Number of spaces for hard tab expansion. Default: 8. Option: ``--tab-width``. trim_footnote_reference_space ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Remove spaces before `footnote references`_? Default: None [#]_ Options: ``--trim-footnote-reference-space, --leave-footnote-reference-space``. .. [#] 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". .. _myst: [myst parser] ------------- Provided by the 3rd party package `myst-docutils`_. See `MyST with Docutils`_ and its `Sphinx configuration options`_ (some settings are not available with Docutils). .. _myst-docutils: https://pypi.org/project/myst-docutils/ .. _MyST with Docutils: https://myst-parser.readthedocs.io/en/latest/docutils.html .. _Sphinx configuration options: https://myst-parser.readthedocs.io/en/latest/sphinx/reference.html#sphinx-config-options .. _pycmark: [pycmark parser] ---------------- Provided by the 3rd party package `pycmark`__. Currently no configuration settings. __ https://pypi.org/project/pycmark/ .. _recommonmark: [recommonmark parser] --------------------- Provisional, depends on (deprecated) 3rd-party package recommonmark__. Currently no configuration settings. __ https://pypi.org/project/recommonmark/ [readers] ========= [standalone reader] ------------------- docinfo_xform ~~~~~~~~~~~~~ Enable or disable the `bibliographic field list`_ transform (docutils.transforms.frontmatter.DocInfo). Default: enabled (True). Options: ``--no-doc-info``. doctitle_xform ~~~~~~~~~~~~~~ Enable or disable the promotion of a lone top-level section title to `document title`_ (and subsequent section title to document subtitle promotion; docutils.transforms.frontmatter.DocTitle). Default: enabled (True). Options: ``--no-doc-title``. sectsubtitle_xform ~~~~~~~~~~~~~~~~~~ Enable or disable the promotion of the title of a lone subsection to a subtitle (docutils.transforms.frontmatter.SectSubTitle). Default: disabled (False). Options: ``--section-subtitles, --no-section-subtitles``. [pep reader] ------------ The `pep_references`_ and `rfc_references`_ settings (`[restructuredtext parser]`_) are set on by default. .. [python reader] --------------- Not implemented. [writers] ========= [docutils_xml writer] --------------------- .. Caution:: * The XML declaration carries text encoding information. If the encoding is not UTF-8 or ASCII and the XML declaration is missing, standard tools may be unable to read the generated XML. doctype_declaration ~~~~~~~~~~~~~~~~~~~ Generate XML with a DOCTYPE declaration. Default: do (True). Options: ``--no-doctype``. indents ~~~~~~~ Generate XML with indents and newlines. Default: don't (None). Options: ``--indents``. newlines ~~~~~~~~ Generate XML with newlines before and after tags. Default: don't (None). Options: ``--newlines``. .. _xml_declaration [docutils_xml writer]: xml_declaration ~~~~~~~~~~~~~~~ Generate XML with an XML declaration. See also `xml_declaration [html writers]`_. Default: do (True). Option: ``--no-xml-declaration``. [html writers] -------------- .. _attribution [html writers]: attribution ~~~~~~~~~~~ Format 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_addresses ~~~~~~~~~~~~~~~~~~~~~ Scramble email addresses to confuse harvesters. In the reference URI, the "@" will be replaced by %-escapes (as of RFC 1738). In the visible text (link text) of an email reference, the "@" and all periods (".") will be surrounded by ```` 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:: abc@example.org .. Note:: While cloaking email addresses will have little to no impact on the rendering and usability of email links in most browsers, some browsers (e.g. the ``links`` browser) may decode cloaked email addresses incorrectly. Default: don't cloak (None). Option: ``--cloak-email-addresses``. compact_lists ~~~~~~~~~~~~~ Remove extra vertical whitespace between items of `bullet lists`_ and `enumerated lists`_, when list items are all "simple" (i.e., items each contain one paragraph and/or one "simple" 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``. compact_field_lists ~~~~~~~~~~~~~~~~~~~ Remove extra vertical whitespace between items of `field lists`_ that are "simple" (i.e., all field bodies each contain at most one paragraph). The behaviour can be specified directly via "class" attributes (values "compact" and "open") in the document. Default: enabled (True). Options: ``--compact-field-lists, --no-compact-field-lists``. .. _embed_stylesheet [html writers]: embed_stylesheet ~~~~~~~~~~~~~~~~ Embed the stylesheet in the output HTML file. The stylesheet file must specified by the stylesheet_path_ setting and must be accessible during processing. See also `embed_stylesheet [latex writers]`_. Default: enabled. Options: ``--embed-stylesheet, --link-stylesheet``. .. _footnote_references setting: .. _footnote_references [html writers]: footnote_references ~~~~~~~~~~~~~~~~~~~ Format for `footnote references`_, one of "superscript" or "brackets". See also `footnote_references [latex writers]`_. Overrides [#override]_ trim_footnote_reference_space_, if the parser supports this option. Default: "brackets". Option: ``--footnote-references``. initial_header_level ~~~~~~~~~~~~~~~~~~~~ The initial level for header elements. This does not affect the document title & subtitle; see doctitle_xform_. Default: writer dependent (see `[html4css1 writer]`_, `[html5 writer]`_, `[pep_html writer]`_). Option: ``--initial-header-level``. math_output ~~~~~~~~~~~ The format of mathematical content (`math directive`_ and role) in the output document. Supported values are (case insensitive): :HTML: Format math in standard HTML enhanced by CSS rules. Requires the ``math.css`` stylesheet (in the system `stylesheet directory `__) A `stylesheet_path `__ can be appended after whitespace. The specified stylesheet(s) will only be referenced or embedded if required (i.e. if there is mathematical content in the document). :MathJax: Format math for display with MathJax_, a JavaScript-based math rendering engine. Pro: Works across multiple browsers and platforms. Large set of `supported LaTeX math commands and constructs`__ __ http://docs.mathjax.org/en/latest/input/tex/macros/index.html Con: Rendering requires JavaScript and an Internet connection or local MathJax installation. A URL pointing to a MathJax library should be appended after whitespace. A warning is given if this is missing. * It is recommended to install__ the MathJax library on the same server as the rest of the deployed site files. __ https://www.mathjax.org/#installnow 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. __ https://www.mathjax.org/#gettingstarted * Use a local MathJax installation on the *client* machine, e.g.:: math-output: MathJax file:/usr/share/javascript/mathjax/MathJax.js This is the fallback if no URL is specified. :MathML: Embed math content as presentational MathML_. Pro: The W3C recommendation for math on the web. Self-contained documents (no JavaScript, no external downloads). Con: Limited `browser support`__. Docutil's latex2mathml converter supports only a `subset of LaTeX math syntax`__. With the "html4css1" writer, the resulting HTML document does not validate, as there is no DTD for `MathML + XHTML Transitional`. However, MathML-enabled browsers will render it fine. __ https://developer.mozilla.org/en-US/docs/Web/MathML #browser_compatibility __ ../ref/rst/mathematics.html An external converter can be appended after whitespace, e.g., ``--math-output="MathML latexml"``: blahtexml_ Fast conversion, support for many symbols and environments, but no "align" (or other equation-aligning) environment. (C++) LaTeXML_ Comprehensive macro support but *very* slow. (Perl) TtM_ No "matrix", "align" and "cases" environments. Support may be removed. :LaTeX: Include literal LaTeX code. The failsafe fallback. Default: HTML math.css. Option: ``--math-output``. New in Docutils 0.8. .. _math directive: ../ref/rst/directives.html#math .. _MathJax: http://www.mathjax.org/ .. _MathPlayer: http://www.dessci.com/en/products/mathplayer/ .. _MathML: https://www.w3.org/TR/MathML/ .. _blahtexml: http://gva.noekeon.org/blahtexml/ .. _LaTeXML: http://dlmf.nist.gov/LaTeXML/ .. _TtM: http://hutchinson.belmont.ma.us/tth/mml/ .. _stylesheet [html writers]: stylesheet ~~~~~~~~~~ A comma-separated list of CSS stylesheet URLs, used verbatim. See also `stylesheet [latex writers]`_. Overrides also stylesheet_path_. [#override]_ Default: None. Option: ``--stylesheet``. .. _stylesheet_dirs [html writers]: stylesheet_dirs ~~~~~~~~~~~~~~~ A comma-separated list of directories where stylesheets can be found. Used by the stylesheet_path_ setting when expanding relative path arguments. Note: This setting defines a "search path" (similar to the PATH variable for executables). However, the term "path" is already used in the stylesheet_path_ setting with the meaning of a file location. Default: the working directory of the process at launch and the directory with default stylesheet files (writer and installation specific). Use the ``--help`` option to get the exact value. Option: ``--stylesheet-dirs``. .. _stylesheet_path: .. _stylesheet_path [html writers]: stylesheet_path ~~~~~~~~~~~~~~~ A comma-separated list of paths to CSS stylesheets. Relative paths are expanded if a matching file is found in the stylesheet_dirs__. If embed_stylesheet__ is False, paths are rewritten relative to the output HTML file. See also `stylesheet_path [latex writers]`_. Also overrides "stylesheet". [#override]_ 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``. __ `embed_stylesheet [html writers]`_ __ `stylesheet_dirs [html writers]`_ .. _table_style [html writers]: table_style ~~~~~~~~~~~ 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 ```` 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``. .. _table directive: ../ref/rst/directives.html#table .. _template [html writers]: template ~~~~~~~~ Path to template file, which must be encoded in UTF-8. [#pwd]_ 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``. .. _xml_declaration [html writers]: xml_declaration ~~~~~~~~~~~~~~~ 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``. [html4css1 writer] ~~~~~~~~~~~~~~~~~~ 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 Defaults """""""""""""""""""""""" `initial_header_level`_ 1 (for "

") `stylesheet_path `__: "html4css1.css" `xml_declaration `__ enabled (True) .. _HTML4/CSS1 Writer: html.html#html4css1 .. _XHTML 1 Transitional: https://www.w3.org/TR/xhtml1/ field_name_limit """""""""""""""" The maximum width (in characters) for one-column `field names`_. Longer field names will span an entire row of the table used to render the field list. 0 indicates "no limit". See also option_limit_. Default: 14 (i.e. 14 characters). Option: ``--field-name-limit``. option_limit """""""""""" The maximum width (in characters) for options in `option lists`_. Longer options will span an entire row of the table used to render the option list. 0 indicates "no limit". See also field_name_limit_. Default: 14 (i.e. 14 characters). Option: ``--option-limit``. [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. .. _HTML5 Writer: html.html#html5-polyglot .. _HTML5: https://www.w3.org/TR/2014/REC-html5-20141028/ Writer Specific Defaults """""""""""""""""""""""" `initial_header_level`_ 2 (for "

", cf. the "`The h1, h2, h3, h4, h5, and h6 elements`__" in the HTML Standard) `stylesheet_path `__: "minimal.css, plain.css" __ https://html.spec.whatwg.org/multipage/sections.html #the-h1,-h2,-h3,-h4,-h5,-and-h6-elements embed_images """""""""""" Deprecated. Obsoleted by image_loading_. 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. .. _base64: https://en.wikipedia.org/wiki/Base64 .. _data URI: https://en.wikipedia.org/wiki/Data_URI_scheme .. _lazy loading attribute: https://html.spec.whatwg.org/multipage/ urls-and-fetching.html#lazy-loading-attributes section_self_link """"""""""""""""" 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. [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 Defaults """""""""""""""""""""""" `initial_header_level`_ 1 (for "

") `stylesheet_path `__: "pep.css" `template