docutils/docs/user/config.txt

   1 .. include:: ../header.txt
   2
   3 ========================
   4  Docutils Configuration
   5 ========================
   6
   7 :Author: David Goodger
   8 :Contact: docutils-develop@lists.sourceforge.net
   9 :Revision: $Revision$
  10 :Date: $Date$
  11 :Copyright: This document has been placed in the public domain.
  12
  13 .. sidebar:: Docutils Security for Web Applications
  14
  15    For a discussion about securing web applications, please see
  16    `Deploying Docutils Securely <../howto/security.html>`_.
  17
  18 .. contents::
  19
  20 .. raw:: html
  21
  22    <style type="text/css"><!--
  23     dl.field-list {--field-indent: 4.7em;}
  24     --></style>
  25
  26
  27 Introduction
  28 ============
  29
  30 Settings priority
  31 -----------------
  32
  33 Configuration file settings override the built-in defaults, and
  34 command-line options override all.
  35 Some settings override also an associated setting; [#override]_
  36 others append values from the various sources. [#append-values]_
  37
  38 For the technicalities, see `Docutils Runtime Settings`_.
  39
  40
  41 Configuration Files
  42 -------------------
  43
  44 Configuration files are used for persistent customization;
  45 they can be set once and take effect every time you use a component,
  46 e.g., via a `front-end tool`_.
  47
  48 By default, Docutils checks the following places for configuration
  49 files, in the following order:
  50
  51 1. ``/etc/docutils.conf``: This is a system-wide configuration file,
  52    applicable to all Docutils processing on the system.
  53
  54 2. ``./docutils.conf``: This is a project-specific configuration file,
  55    located in the current directory.
  56    The Docutils front end has to be executed from the directory
  57    containing this configuration file for it to take effect (note that
  58    this may have nothing to do with the location of the source files).
  59
  60 3. ``~/.docutils``: This is a user-specific configuration file,
  61    located in the user's home directory.
  62
  63 If more than one configuration file is found, all will be read and
  64 **later entries** will **override earlier ones**. [#append-values]_
  65 For example, a "stylesheet" entry in a user-specific configuration file
  66 will override a "stylesheet" entry in the system-wide file.
  67
  68 .. _DOCUTILSCONFIG:
  69
  70 The default implicit config file paths can be overridden by the
  71 ``DOCUTILSCONFIG`` environment variable.  ``DOCUTILSCONFIG`` should
  72 contain a colon-separated (semicolon-separated on Windows) sequence of
  73 config file paths to search for; leave it empty to disable implicit
  74 config files altogether.  Tilde-expansion is performed on paths.
  75 Paths are interpreted relative to the current working directory.
  76 Empty path items are ignored.
  77
  78 .. |config| replace:: ``--config``
  79
  80 In addition, configuration files may be explicitly specified with the
  81 |config|_ command-line option.  These configuration files are read after
  82 the three implicit ones listed above (or the ones defined by the
  83 ``DOCUTILSCONFIG`` environment variable), and its entries will have
  84 priority.
  85
  86
  87 Configuration File Syntax
  88 -------------------------
  89
  90 Configuration files are UTF-8-encoded text files.  The ConfigParser.py_
  91 module from Python_'s standard library is used to read them.
  92 From its documentation:
  93
  94     The configuration file consists of sections, lead by a "[section]"
  95     header and followed by "name: value" entries, with continuations
  96     in the style of `RFC 822`_; "name=value" is also accepted.  Note
  97     that leading whitespace is removed from values.  ...  Lines
  98     beginning with "#" or ";" are ignored and may be used to provide
  99     comments.
 100
 101 .. Note:: No format string interpolation is done.
 102
 103 The following conventions apply to Docutils configuration files:
 104
 105 * Configuration file **entry names** correspond to internal `runtime
 106   settings`_.  Underscores ("_") and hyphens ("-") can be used interchangeably
 107   in entry names; hyphens are automatically converted to underscores.
 108   Entries with non-applicable or misspelled entry names are silently ignored.
 109
 110   .. _boolean:
 111
 112 * For **boolean** settings (switches), the following values are
 113   recognized (case-independent):
 114
 115   :True: "true", "yes", "on", "1"
 116   :False: "false", "no", "off", "0", "" (no value)
 117
 118 .. _comma-separated:
 119
 120 * **Lists** are specified either comma- or _`colon-separated`:
 121
 122   *comma-separated*:
 123     strip_classes_, strip_elements_with_classes_, smartquotes_locales_,
 124     stylesheet_, stylesheet_dirs_, stylesheet_path_, use_bibtex_
 125
 126     Whitespace around list values is stripped, so you can write, e.g., ::
 127
 128       strip-classes: ham,eggs,
 129       strip-elements-with-classes: sugar, salt, flour
 130       stylesheet: html4css1.css,
 131                   math.css,
 132                   style sheet with spaces.css
 133
 134
 135   *colon-separated*:
 136     ignore_, prune_, sources_, expose_internals_
 137
 138     Whitespace around the delimiter is not stripped. Write, e.g., ::
 139
 140       expose_internals: source:line
 141
 142
 143 Example
 144 ~~~~~~~
 145
 146 This is from the ``tools/docutils.conf`` configuration file supplied
 147 with Docutils::
 148
 149     # These entries affect all processing:
 150     [general]
 151     source-link: yes
 152     datestamp: %Y-%m-%d %H:%M UTC
 153     generator: on
 154
 155     # These entries affect HTML output:
 156     [html writers]
 157     embed-stylesheet: no
 158
 159     [html4css1 writer]
 160     stylesheet-path: docutils/writers/html4css1/html4css1.css
 161     field-name-limit: 20
 162
 163     [html5 writer]
 164     stylesheet-dirs: docutils/writers/html5_polyglot/
 165     stylesheet-path: minimal.css, responsive.css
 166
 167
 168 .. _configuration section:
 169 .. _configuration sections:
 170
 171 Configuration File Sections & Entries
 172 -------------------------------------
 173
 174 Below are the Docutils `runtime settings`_, listed by config file section.
 175 Sections correspond to Docutils components (module name
 176 or alias; section names are always in lowercase letters).
 177
 178 .. important:: Any setting may be specified in any section, but only
 179                settings from "`active sections`_" will be used.
 180
 181
 182 .. _active sections:
 183
 184 Each Docutils application_ uses a specific set of components;
 185 `corresponding configuration file sections`__ are "active" when the
 186 application is used.
 187
 188 Configuration sections are applied in general-to-specific order:
 189
 190 1. `[general]`_
 191
 192 2. `[parsers]`_, parser dependencies, and the section specific to the
 193    Parser used ("[... parser]").
 194
 195 3. `[readers]`_, reader dependencies, and the section specific to the
 196    Reader used ("[... reader]").  For example, `[pep reader]`_ depends
 197    on `[standalone reader]`_.
 198
 199 4. `[writers]`_, writer family ("[... writers]"; if applicable),
 200    writer dependencies, and the section specific to the writer used
 201    ("[... writer]").  For example, `[pep_html writer]`_ depends
 202    on `[html writers]`_ and `[html4css1 writer]`_.
 203
 204 5. `[applications]`_, application dependencies, and the section
 205    specific to the Application (`front-end tool`_) in use
 206    ("[... application]").
 207
 208 Since any setting may be specified in any section, this ordering
 209 allows component- or application-specific overrides of earlier
 210 settings.  For example, there may be Reader-specific overrides of
 211 general settings; Writer-specific overrides of Parser settings;
 212 Application-specific overrides of Writer settings; and so on.
 213
 214 If multiple configuration files are applicable, the process is
 215 completed (all sections are applied in the order given) for each one
 216 before going on to the next.  For example, a "[pep_html writer]
 217 stylesheet" setting in an earlier configuration file would be
 218 overridden by an "[html4css1 writer] stylesheet" setting in a later
 219 file.
 220
 221 Individual configuration sections and settings are described
 222 in the following sections.
 223 Some knowledge of Python_ is assumed for some attributes.
 224
 225
 226 .. _ConfigParser.py:
 227    https://docs.python.org/3/library/configparser.html
 228 .. _Python: https://www.python.org/
 229 .. _RFC 822: https://www.rfc-editor.org/rfc/rfc822.txt
 230 .. _front-end tool:
 231 .. _front-end tools:
 232 .. _application: tools.html
 233 __ ../api/runtime-settings.html#active-sections
 234
 235
 236 [general]
 237 =========
 238
 239 Settings in the "[general]" section are always applied.
 240
 241
 242 auto_id_prefix
 243 --------------
 244
 245 Prefix prepended to all auto-generated `identifier keys` generated within
 246 the document, after id_prefix_. Ensure the value conforms to the
 247 restrictions on identifiers in the output format, as it is not subjected to
 248 the `identifier normalization`_.
 249
 250 A trailing "%" is replaced with the tag name (new in Docutils 0.16).
 251
 252 :Default: "%" (changed in 0.18 from "id").
 253 :Option:  ``--auto-id-prefix`` (hidden, intended mainly for programmatic use).
 254
 255 .. _identifier normalization:
 256    ../ref/rst/directives.html#identifier-normalization
 257
 258
 259 datestamp
 260 ---------
 261
 262 Include a time/datestamp in the document footer.  Contains a
 263 format string for Python's `time.strftime()`__.
 264
 265 Configuration file entry examples::
 266
 267     # Equivalent to --date command-line option, results in
 268     # ISO 8601 extended format datestamp, e.g. "2001-12-21":
 269     datestamp: %Y-%m-%d
 270
 271     # Equivalent to --time command-line option, results in
 272     # date/timestamp like "2001-12-21 18:43 UTC":
 273     datestamp: %Y-%m-%d %H:%M UTC
 274
 275     # Disables datestamp; equivalent to --no-datestamp:
 276     datestamp:
 277
 278 :Default: None.
 279 :Options: ``--date``, ``-d``, ``--time``, ``-t``, ``--no-datestamp``.
 280
 281 __ https://docs.python.org/3/library/time.html#time.strftime
 282
 283
 284 debug
 285 -----
 286
 287 Report debug-level system messages.
 288
 289 *Default*: None (disabled).  *Options*: ``--debug``, ``--no-debug``.
 290
 291
 292 dump_internals
 293 --------------
 294
 295 At the end of processing, write all internal attributes of the
 296 document (``document.__dict__``) to stderr.
 297
 298 *Default*: None (disabled).
 299 *Option*: ``--dump-internals`` (hidden, for development use only).
 300
 301
 302 dump_pseudo_xml
 303 ---------------
 304
 305 At the end of processing, write the pseudo-XML representation of
 306 the document to stderr.
 307
 308 *Default*: None (disabled).
 309 *Option*: ``--dump-pseudo-xml`` (hidden, for development use only).
 310
 311
 312 dump_settings
 313 -------------
 314
 315 At the end of processing, write all Docutils settings to stderr.
 316
 317 *Default*: None (disabled).
 318 *Option*: ``--dump-settings`` (hidden, for development use only).
 319
 320
 321 dump_transforms
 322 ---------------
 323
 324 At the end of processing, write a list of all transforms applied
 325 to the document to stderr.
 326
 327 *Default*: None (disabled).
 328 *Option*: ``--dump-transforms`` (hidden, for development use only).
 329
 330
 331 error_encoding
 332 --------------
 333
 334 The text encoding for error output.
 335
 336 :Default: The encoding reported by ``sys.stderr``, locale encoding, or "ascii".
 337 :Options: ``--error-encoding``, ``-e``.
 338
 339
 340 error_encoding_error_handler
 341 ----------------------------
 342
 343 The error handler for unencodable characters in error output.
 344 Acceptable values are the `Error Handlers`_ of Python's "codecs" module.
 345 See also output_encoding_error_handler_.
 346
 347 :Default: "backslashreplace"
 348 :Options: ``--error-encoding-error-handler``, ``--error-encoding``, ``-e``.
 349
 350
 351 exit_status_level
 352 -----------------
 353
 354 A system message level threshold; non-halting system messages at
 355 or above this level will produce a non-zero exit status at normal
 356 exit.  Exit status is the maximum system message level plus 10 (11
 357 for INFO, etc.).
 358
 359 *Default*: 5 (disabled).  *Option*: ``--exit-status``.
 360
 361
 362 expose_internals
 363 ----------------
 364
 365 List of internal attributes (colon-separated_) to expose
 366 as external attributes (with "internal:" namespace prefix).
 367 Values are appended. [#append-values]_
 368
 369 *Default*: empty list.
 370 *Option*: ``--expose-internal-attribute`` (hidden, for development use only).
 371
 372
 373 footnote_backlinks
 374 ------------------
 375
 376 Enable backlinks from footnotes_ and citations_ to their references.
 377
 378 :Default: True.
 379 :Options: ``--footnote-backlinks``, ``--no-footnote-backlinks``.
 380
 381
 382 generator
 383 ---------
 384
 385 Include a "Generated by Docutils" credit and link in the document footer.
 386
 387 :Default: None (disabled).
 388 :Options: ``--generator``, ``-g``, ``--no-generator``.
 389
 390
 391 halt_level
 392 ----------
 393
 394 The threshold at or above which system messages are converted to
 395 exceptions, halting execution immediately.  If `traceback`_ is set, the
 396 exception will propagate; otherwise, Docutils will exit.
 397
 398 See also report_level_.
 399
 400 *Default*: 4 (severe).  *Options*: ``--halt``, ``--strict``.
 401
 402
 403 id_prefix
 404 ---------
 405
 406 Prefix prepended to all identifier keys generated within the document.
 407 Ensure the value conforms to the restrictions on identifiers in the output
 408 format, as it is not subjected to the `identifier normalization`_.
 409 See also auto_id_prefix_.
 410
 411 *Default*: "" (no prefix).
 412 *Option*: ``--id-prefix`` (hidden, intended mainly for programmatic use).
 413
 414
 415 input_encoding
 416 --------------
 417
 418 The text encoding for input.
 419
 420 *Default*: utf-8. [#]_
 421 *Option*: ``--input-encoding`` [#i-o-options]_
 422
 423 .. [#] The default changed from None (auto-detect_) to "utf-8" in
 424        Docutils 0.22.
 425 .. [#i-o-options] The short options ``-i`` and ``-o`` were removed
 426                   in Docutils 0.22.
 427
 428 .. _auto-detect: ../api/publisher.html#encodings
 429
 430
 431 input_encoding_error_handler
 432 ----------------------------
 433
 434 The error handler for undecodable characters in the input.
 435 Acceptable values are the `Error Handlers`_ of Python's "codecs" module,
 436 including:
 437
 438 strict
 439     Raise an exception in case of an encoding error.
 440 replace
 441     Replace malformed data with the official Unicode replacement
 442     character, U+FFFD.
 443 ignore
 444     Ignore malformed data and continue without further notice.
 445
 446 The error handler may also be appended to the input_encoding_
 447 setting, delimited by a colon, e.g. ``--input-encoding=ascii:replace``.
 448
 449 *Default*: "strict".
 450 *Options*: ``--input-encoding-error-handler``.
 451
 452
 453 language_code
 454 -------------
 455
 456 Case-insensitive `language tag`_ as defined in `BCP 47`_.
 457
 458 Sets the document language, also used for localized directive and
 459 role names as well as Docutils-generated text.
 460
 461 A typical language identifier consists of a 2-letter language code
 462 from `ISO 639`_ (3-letter codes can be used if no 2-letter code
 463 exists). The language identifier can have an optional subtag,
 464 typically for variations based on country (from `ISO 3166`_
 465 2-letter country codes).  Avoid subtags except where they add
 466 useful distinguishing information. Examples of language tags
 467 include "fr", "en-GB", "pt-br" (the same as "pt-BR"), and
 468 "de-1901" (German with pre-1996 spelling).
 469
 470 The language of document parts can be specified with a
 471 "language-<language tag>" `class attribute`_, e.g.
 472 ``.. class:: language-el-polyton`` for a quote in polytonic Greek.
 473
 474 *Default*: "en" (English).  *Options*: ``--language``, ``-l``.
 475
 476 .. _class attribute: ../ref/doctree.html#classes
 477
 478
 479 output
 480 ------
 481
 482 The path of the output destination.
 483 An existing file will be overwritten without warning.
 484 Use "-" for `stdout`.
 485
 486 Obsoletes the `\<destination>`_ positional argument
 487 (cf. `Future changes`_ in the RELEASE-NOTES).
 488
 489 *Default*: None (stdout). *Option*: ``--output``.
 490
 491 New in Docutils 0.20.
 492
 493 .. _Future changes: ../../RELEASE-NOTES.html#future-changes
 494
 495
 496 output_encoding
 497 ---------------
 498
 499 The text encoding for output.
 500
 501 The "output_encoding" setting may also affect the content of the output
 502 (e.g. an encoding declaration in HTML or XML or the representation of
 503 characters as LaTeX macro vs. literal character).
 504
 505 This setting is ignored by the `ODF/ODT Writer`_ which always usues UTF-8.
 506
 507 *Default*: "utf-8".  *Option*: ``--output-encoding``. [#i-o-options]_
 508
 509
 510 output_encoding_error_handler
 511 -----------------------------
 512
 513 The error handler for unencodable characters in the output.
 514 Acceptable values are the `Error Handlers`_ of Python's "codecs" module,
 515 including:
 516
 517 strict
 518     Raise an exception in case of an encoding error.
 519 replace
 520     Replace malformed data with a suitable replacement marker,
 521     such as "?".
 522 ignore
 523     Ignore malformed data and continue without further notice.
 524 xmlcharrefreplace
 525     Replace with the appropriate XML character reference, such as
 526     "``&#8224;``".
 527 backslashreplace
 528     Replace with backslash escape sequences, such as "``\u2020``".
 529
 530 The error handler may also be appended to the output_encoding_
 531 setting using a colon as delimiter, e.g.
 532 ``--output-encoding=ascii:xmlcharrefreplace``.
 533
 534 *Default*: "strict".
 535 *Options*: ``--output-encoding-error-handler``.
 536
 537
 538 record_dependencies
 539 -------------------
 540
 541 Path to a file where Docutils will write a list of files that
 542 were required to generate the output, e.g. included files or embedded
 543 stylesheets. [#dependencies]_  The format is one path per line with
 544 forward slashes as separator, the encoding is UTF-8.
 545
 546 Set it to "-" in order to write dependencies to stdout.
 547
 548 This option is particularly useful in conjunction with programs like
 549 ``make`` using ``Makefile`` rules like::
 550
 551   ham.html: ham.txt $(shell cat hamdeps.txt)
 552     rst2html --record-dependencies=hamdeps.txt ham.txt > ham.html
 553
 554 If the filesystem encoding differs from UTF-8, replace the ``cat``
 555 command with a call to a converter, e.g.::
 556
 557   $(shell iconv -f utf-8 -t latin1 hamdeps.txt)
 558
 559 *Default*: None (disabled).  *Option*: ``--record-dependencies``.
 560
 561 .. [#dependencies] Images are only added to the dependency list if they
 562    are embedded into the output or the reStructuredText parser extracted
 563    image dimensions from the file.
 564
 565
 566 report_level
 567 ------------
 568
 569 Report system messages at or higher than <level>:
 570
 571   1  info
 572   2  warning
 573   3  error
 574   4  severe
 575   5  none
 576
 577 See also halt_level_.
 578
 579 :Default: 2 (warning).
 580 :Options: ``--report``, ``-r``, ``--verbose``, ``-v``, ``--quiet``, ``-q``.
 581
 582
 583 root_prefix
 584 -----------
 585
 586 Base directory, prepended to a filesystem path__ starting with "/" when
 587 including files with the `"include"`_, `"raw"`_, or `"csv-table"`_
 588 directives.
 589
 590 Also applied when a writer converts an image URI__ to a local filesystem
 591 path in order to determine the image size or embed the image in the output.
 592
 593 :Default: "/" (keep paths unchanged).
 594 :Option:  ``--root-prefix``
 595
 596 New in Docutils 0.21.
 597
 598 __ ../ref/rst/directives.html#path
 599 __ ../ref/rst/directives.html#uri
 600
 601
 602 sectnum_xform
 603 -------------
 604
 605 Enable automatic section numbering by Docutils
 606 (`docutils.transforms.parts.SectNum`) associated
 607 with the `"sectnum" directive`_.
 608
 609 If disabled, section numbers might be added to the output by the
 610 renderer (e.g. by LaTeX or via a CSS style definition).
 611
 612 :Default: True.
 613 :Options: ``--section-numbering``, ``--no-section-numbering``.
 614
 615
 616 source_link
 617 -----------
 618
 619 Include a "View document source" link in the document footer.  URL will
 620 be relative to the destination.
 621
 622 :Default: None (disabled).
 623 :Options: ``--source-link``, ``-s``, ``--no-source-link``.
 624
 625
 626 source_url
 627 ----------
 628
 629 An explicit URL for a "View document source" link, used verbatim.
 630
 631 :Default: None (compute from source_link_).
 632 :Options: ``--source-url``, ``--no-source-link``.
 633
 634
 635 strict_visitor
 636 --------------
 637
 638 When processing a `document tree`_ with the Visitor pattern, raise an
 639 error if a writer does not support a node type listed as optional.
 640 For transitional development use.
 641
 642 :Default: None (disabled).
 643 :Option:  ``--strict-visitor`` (hidden, for development use only).
 644
 645
 646 strip_classes
 647 -------------
 648
 649 List of "classes" attribute values (comma-separated_) that will be
 650 removed from all elements in the `document tree`_.
 651 Values are appended. [#append-values]_
 652
 653 Allows eliding class values that interfere with, e.g, CSS rules from 3rd
 654 party tools/frameworks.
 655
 656 .. WARNING:: Some standard class values are required in order to achieve
 657              the expected output rendering; use with caution.
 658
 659 *Default*: empty list.  *Option*: ``--strip-class``.
 660
 661
 662 strip_comments
 663 --------------
 664
 665 Enable or disable the removal of comment elements from the `document tree`_.
 666
 667 :Default: None (disabled).
 668 :Options: ``--strip-comments``, ``--leave-comments``.
 669
 670
 671 strip_elements_with_classes
 672 ---------------------------
 673
 674 List of "classes" attribute values (comma-separated_).
 675 Values are appended. [#append-values]_
 676 Matching elements are removed from the `document tree`_.
 677
 678 .. WARNING:: Potentially dangerous: may lead to an invalid document tree
 679    and subsequent writer errors.  Use with caution.
 680
 681 *Default*: empty list.  *Option*: ``--strip-elements-with-class``.
 682
 683
 684 title
 685 -----
 686
 687 The `document title` as metadata which does not become part of the
 688 document body. Stored as the document's `title attribute`_.
 689 For example, in HTML output the metadata document title
 690 appears in the title bar of the browser window.
 691
 692 This setting overrides a displayed `document title`_ and
 693 is overridden by a `"title" directive`_.
 694
 695 :Default: None (the displayed `document title`_).
 696 :Option:  ``--title``.
 697
 698 .. _title attribute: ../ref/doctree.html#title-attribute
 699
 700
 701 toc_backlinks
 702 -------------
 703
 704 Enable backlinks from section titles to table of contents entries
 705 ("entry"), to the top of the ToC ("top"), or disable (False).
 706
 707 :Default: "entry".
 708 :Options: ``--toc-entry-backlinks``, ``--toc-top-backlinks``,
 709           ``--no-toc-backlinks``.
 710
 711
 712 traceback
 713 ---------
 714
 715 Enable or disable Python tracebacks when halt-level system messages and
 716 other exceptions occur.  Useful for debugging, and essential for issue
 717 reports.  Exceptions are allowed to propagate, instead of being
 718 caught and reported (in a user-friendly way) by Docutils.
 719
 720 :Default: None (disabled). [#]_
 721 :Options: ``--traceback``, ``--no-traceback``.
 722
 723 .. [#] unless Docutils is run programmatically
 724        using the `Publisher Interface`_
 725
 726
 727 warning_stream
 728 --------------
 729
 730 Path [#pwd]_ to a file for the output of system messages (warnings).
 731
 732 *Default*: None (stderr).  *Option*: ``--warnings``.
 733
 734
 735 [parsers]
 736 =========
 737
 738 Generic parser options:
 739
 740 file_insertion_enabled
 741 ----------------------
 742
 743 Enable directives inserting the contents of external files,
 744 such as `"include"`_ directive or the `"raw"`_ and `"csv-table"`_
 745 directives with option "url" or "file".
 746 A "warning" system message (including the directive text) is inserted
 747 instead.  (See also raw_enabled_ for another security-relevant setting.)
 748
 749 :Default: True.
 750 :Options: ``--file-insertion-enabled``, ``--no-file-insertion``.
 751
 752
 753 line_length_limit
 754 -----------------
 755
 756 Maximal number of characters in an input line or `"substitution"`_
 757 definition. To prevent extraordinary high processing times or memory
 758 usage for certain input constructs, a "warning" system message is
 759 inserted instead.
 760
 761 *Default*: 10 000.
 762 *Option*: ``--line-length-limit``
 763
 764 New in Docutils 0.17.
 765
 766
 767 raw_enabled
 768 -----------
 769
 770 Enable the `"raw" directive`_.  A "warning" system message
 771 (including the directive text) is inserted instead.  See also
 772 file_insertion_enabled_ for another security-relevant setting.
 773
 774 *Default*: True.  *Options*: ``--raw-enabled``, ``--no-raw``.
 775
 776
 777 validate
 778 --------
 779
 780 Validate the parsing result.
 781
 782 *Default*: False.  *Options*: ``--validate``, ``--no-validation``.
 783
 784
 785 [restructuredtext parser]
 786 -------------------------
 787
 788 character_level_inline_markup
 789 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 790 Relax the `inline markup recognition rules`_
 791 requiring whitespace or punctuation around inline markup.
 792
 793 Allows character level inline markup without escaped whithespace and is
 794 especially suited for languages that do not use whitespace to separate words
 795 (e.g. Japanese, Chinese).
 796
 797 .. WARNING:: Potentially dangerous; use with caution.
 798
 799    When changing this setting to "True", inline markup characters in
 800    URLs, names and formulas must be escaped to prevent recognition and
 801    possible errors.
 802
 803    Examples:
 804      .. class:: borderless
 805
 806      ===========================  ====================================
 807      ``http://rST_for_all.html``  hyperlinks to ``rST_`` and ``for_``
 808      ``x_2, inline_markup``       hyperlinks to ``x_`` and ``inline_``
 809      ``2*x``                      starts emphasised text
 810      ``a|b``                      starts a substitution reference
 811      ===========================  ====================================
 812
 813 :Default: False.
 814 :Options: ``--character-level-inline-markup``, ``--word-level-inline-markup``.
 815
 816 New in Docutils 0.13.
 817
 818 pep_references
 819 ~~~~~~~~~~~~~~
 820 Recognize and link to standalone PEP references (like "PEP 258").
 821
 822 :Default: None (disabled); True in PEP Reader.
 823 :Option:  ``--pep-references``.
 824
 825 pep_base_url
 826 ~~~~~~~~~~~~
 827 Base URL for PEP references.
 828
 829 *Default*: "https://peps.python.org/".
 830 *Option*: ``--pep-base-url``.
 831
 832 pep_file_url_template
 833 ~~~~~~~~~~~~~~~~~~~~~
 834 Template for PEP file part of URL, interpolated with the PEP
 835 number and appended to pep_base_url_.
 836
 837 *Default*: "pep-%04d".  *Option*: ``--pep-file-url``.
 838
 839 rfc_references
 840 ~~~~~~~~~~~~~~
 841 Recognize and link to standalone RFC references (like "RFC 822").
 842
 843 :Default: None (disabled); True in PEP Reader.
 844 :Option:  ``--rfc-references``.
 845
 846 rfc_base_url
 847 ~~~~~~~~~~~~
 848 Base URL for RFC references.
 849
 850 *Default*: "http://www.faqs.org/rfcs/".  *Option*: ``--rfc-base-url``.
 851
 852 smart_quotes
 853 ~~~~~~~~~~~~
 854 Activate the SmartQuotes_ transform to
 855 change straight quotation marks to typographic form. `Quote characters`_
 856 are selected according to the language of the current block element (see
 857 language_code_, smartquotes_locales_, and the `pre-defined quote sets`_).
 858
 859 Also changes consecutive runs of hyphen-minus and full stops (``---``,
 860 ``--``, ``...``) to em-dash, en-dash, and ellipsis Unicode characters
 861 respectively.
 862
 863 Supported values:
 864
 865 :boolean_: Use smart quotes?
 866 :alt:       Use alternative quote set (if defined for the language).
 867
 868 *Default*: None (disabled). *Option*: ``--smart-quotes``.
 869
 870 .. _SmartQuotes: smartquotes.html
 871 .. _pre-defined quote sets: smartquotes.html#localization
 872 .. _quote characters:
 873    https://en.wikipedia.org/wiki/Non-English_usage_of_quotation_marks
 874
 875 smartquotes_locales
 876 ~~~~~~~~~~~~~~~~~~~
 877
 878 List with language tag and a string of four typographical quote
 879 characters (primary open/close, secondary open/close) for use by
 880 the SmartQuotes_ transform.
 881 Values are appended. [#append-values]_
 882
 883 Example:
 884   Ensure a correct leading apostrophe in ``'s Gravenhage`` in Dutch (at the
 885   cost of incorrect opening single quotes) and set French quotes to double
 886   and single guillemets with inner padding [#]_::
 887
 888           smartquote-locales: nl: „”’’,
 889                               fr: « : »:‹ : ›
 890
 891 :Default: SmartQuotes' `pre-defined quote sets`_.
 892 :Option:  ``--smartquotes-locales``.
 893
 894 New in Docutils 0.14.
 895
 896 .. [#] If more than one character per quote is required (e.g. padding in
 897        French quotes), a colon-separated list may be used for the quote set.
 898
 899 syntax_highlight
 900 ~~~~~~~~~~~~~~~~
 901 Token type names used by Pygments_ when parsing contents of the `"code"`_
 902 directive and role.
 903
 904 Supported values:
 905
 906 :long:  Use hierarchy of long token type names.
 907 :short: Use short token type names.
 908         (For use with `Pygments-generated stylesheets`_.)
 909 :none:  No code parsing. Use this to avoid the "Pygments not
 910         found" warning when Pygments is not installed.
 911
 912 *Default*: "long".  *Option*: ``--syntax-highlight``.
 913
 914 .. _Pygments: https://pygments.org/
 915 .. _Pygments-generated stylesheets:
 916    https://pygments.org/docs/cmdline/#generating-styles
 917
 918 tab_width
 919 ~~~~~~~~~
 920 Number of spaces for `hard tab expansion`_.
 921
 922 *Default*: 8.  *Option*: ``--tab-width``.
 923
 924 .. _hard tab expansion: ../ref/rst/restructuredtext.html#whitespace
 925
 926 trim_footnote_reference_space
 927 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 928 Remove spaces before `footnote references`_?
 929
 930 :Default: None (depends on the `footnote_references setting`_ [#]_).
 931 :Options: ``--trim-footnote-reference-space``,
 932           ``--leave-footnote-reference-space``.
 933
 934 .. [#] The footnote space is trimmed if the reference style is "superscript",
 935        and it is left if the reference style is "brackets".
 936
 937
 938 [myst parser]
 939 -------------
 940
 941 Parser for Markdown (CommonMark_) with rST-compatibility extensions
 942 provided by the 3rd party package `myst-docutils`_.
 943 See `MyST with Docutils`_ and MyST's `Sphinx configuration options`_
 944 (some settings are not applicable with Docutils).
 945
 946 .. _myst-docutils: https://pypi.org/project/myst-docutils/
 947 .. _MyST with Docutils:
 948    https://myst-parser.readthedocs.io/en/latest/docutils.html
 949 .. _Sphinx configuration options:
 950    https://myst-parser.readthedocs.io/en/latest/sphinx/reference.html#sphinx-config-options
 951
 952
 953 [pycmark parser]
 954 ----------------
 955
 956 Parser for Markdown (CommonMark_)
 957 provided by the 3rd party package `pycmark`_.
 958 Currently no configuration settings.
 959
 960 .. _pycmark: https://pypi.org/project/pycmark/
 961
 962
 963 [recommonmark parser]
 964 ---------------------
 965
 966 Parser for Markdown (CommonMark_)
 967 provided by the 3rd party package recommonmark_.
 968
 969 .. admonition:: Deprecated
 970
 971    Depends on deprecated 3rd-party package recommonmark_.
 972    Support will be removed in Docutils 1.0.
 973
 974 Currently no configuration settings.
 975
 976 .. _recommonmark: https://pypi.org/project/recommonmark/
 977
 978
 979 [xml parser]
 980 ------------
 981
 982 The `Docutils XML parser` processes an XML representation of a
 983 `Docutils Document Tree`_
 984 (e.g. the output of the `Docutils XML writer <[docutils_xml writer]_>`__).
 985
 986 New in Docutils 0.22
 987
 988 Parser Specific Defaults
 989 ~~~~~~~~~~~~~~~~~~~~~~~~
 990 .. class:: run-in narrow
 991
 992 :doctitle_xform_:  False.
 993 :validate_:        True.
 994
 995
 996 [readers]
 997 =========
 998
 999 [standalone reader]
1000 -------------------
1001
1002 docinfo_xform
1003 ~~~~~~~~~~~~~
1004 Enable the `bibliographic field list`_ transform
1005 (docutils.transforms.frontmatter.DocInfo).
1006
1007 *Default*: True.  *Options*: ``--no-doc-info``.
1008
1009 doctitle_xform
1010 ~~~~~~~~~~~~~~
1011 Enable the promotion of a lone top-level section title
1012 to `document title`_ (and subsequent section title to document
1013 subtitle promotion; docutils.transforms.frontmatter.DocTitle).
1014
1015 *Default*: True.  *Options*: ``--no-doc-title``.
1016
1017 sectsubtitle_xform
1018 ~~~~~~~~~~~~~~~~~~
1019 Enable the promotion of the title of a lone subsection
1020 to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
1021
1022 :Default: False.
1023 :Options: ``--section-subtitles``, ``--no-section-subtitles``.
1024
1025
1026 [pep reader]
1027 ------------
1028
1029 The `pep_references`_ and `rfc_references`_ settings
1030 (`[restructuredtext parser]`_) are set on by default.
1031
1032
1033 .. [python reader]
1034    ---------------
1035
1036    Not implemented.
1037
1038
1039 [writers]
1040 =========
1041
1042 [docutils_xml writer]
1043 ---------------------
1044
1045 doctype_declaration
1046 ~~~~~~~~~~~~~~~~~~~
1047 Generate XML with a DOCTYPE declaration.
1048
1049 *Default*: True.  *Options*: ``--no-doctype``.
1050
1051 indents
1052 ~~~~~~~
1053 Generate XML with indents and newlines.
1054
1055 *Default*: None (disabled).  *Options*: ``--indents``.
1056
1057 newlines
1058 ~~~~~~~~
1059 Generate XML with newlines before and after block-level tags.
1060
1061 *Default*: None (disabled).  *Options*: ``--newlines``.
1062
1063
1064 .. _xml_declaration [docutils_xml writer]:
1065
1066 xml_declaration
1067 ~~~~~~~~~~~~~~~
1068 Generate XML with an XML declaration.
1069 See also `xml_declaration [html writers]`_.
1070
1071 .. Caution:: The XML declaration carries text encoding information.
1072    If the encoding is not UTF-8 or ASCII and the XML declaration is
1073    missing, standard tools may be unable to read the generated XML.
1074
1075 *Default*: True.  *Option*: ``--no-xml-declaration``.
1076
1077
1078 [html writers]
1079 --------------
1080
1081 .. _attribution [html writers]:
1082
1083 attribution
1084 ~~~~~~~~~~~
1085 Format for `block quote`_ attributions: one of "dash" (em-dash
1086 prefix), "parentheses"/"parens", or "none".
1087 See also `attribution [latex writers]`_.
1088
1089 *Default*: "dash".  *Option*: ``--attribution``.
1090
1091
1092 cloak_email_addresses
1093 ~~~~~~~~~~~~~~~~~~~~~
1094 Scramble email addresses to confuse harvesters.  In the reference
1095 URI, the "@" will be replaced by %-escapes (as of RFC 1738).  In
1096 the visible text (link text) of an email reference, the "@" and
1097 all periods (".") will be surrounded by ``<span>`` tags.
1098 Furthermore, HTML entities are used to encode these characters in
1099 order to further complicate decoding the email address.  For
1100 example, "abc@example.org" will be output as::
1101
1102     <a class="reference" href="mailto:abc&#37;&#52;&#48;example&#46;org">
1103     abc<span>&#64;</span>example<span>&#46;</span>org</a>
1104
1105 .. Note:: While cloaking email addresses will have little to no
1106    impact on the rendering and usability of email links in most
1107    browsers, some browsers (e.g. the ``links`` browser) may decode
1108    cloaked email addresses incorrectly.
1109
1110 *Default*: None (disabled).  *Option*: ``--cloak-email-addresses``.
1111
1112 compact_lists
1113 ~~~~~~~~~~~~~
1114 Remove extra vertical whitespace between items of `bullet lists`_ and
1115 `enumerated lists`_, when list items are all "simple" (i.e., items
1116 each contain one paragraph and/or one "simple" sub-list only).
1117 With the "html5" writer, the setting can be overridden for individual
1118 lists using the `"class" directive`_ (values "compact" and "open").
1119
1120 :Default: True.
1121 :Options: ``--compact-lists``, ``--no-compact-lists``.
1122
1123
1124 compact_field_lists
1125 ~~~~~~~~~~~~~~~~~~~
1126 Remove extra vertical whitespace between items of `field lists`_ that
1127 are "simple" (i.e., all field bodies each contain at most one paragraph).
1128 With the "html5" writer, the setting can be overridden for individual
1129 lists using the `"class" directive`_ (values "compact" and "open").
1130
1131 :Default: True.
1132 :Options: ``--compact-field-lists``, ``--no-compact-field-lists``.
1133
1134
1135 .. _embed_stylesheet [html writers]:
1136
1137 embed_stylesheet
1138 ~~~~~~~~~~~~~~~~
1139 Embed the stylesheet in the output HTML file.  The stylesheet file
1140 must specified by the stylesheet_path_ setting and must be
1141 accessible during processing.
1142 See also `embed_stylesheet [latex writers]`_.
1143
1144 :Default: True.
1145 :Options: ``--embed-stylesheet``, ``--link-stylesheet``.
1146
1147
1148 .. _footnote_references setting:
1149 .. _footnote_references [html writers]:
1150
1151 footnote_references
1152 ~~~~~~~~~~~~~~~~~~~
1153 Format for `footnote references`_, one of "superscript" or "brackets".
1154 See also `footnote_references [latex writers]`_.
1155
1156 Overrides also trim_footnote_reference_space_,
1157 if the parser supports this option. [#override]_
1158
1159 *Default*: "brackets".  *Option*: ``--footnote-references``.
1160
1161 initial_header_level
1162 ~~~~~~~~~~~~~~~~~~~~
1163 The initial level for section header elements.  This does not affect the
1164 document title & subtitle; see doctitle_xform_.
1165
1166 :Default: writer dependent
1167           (see `[html4css1 writer]`_, `[html5 writer]`_, `[pep_html writer]`_).
1168 :Option:  ``--initial-header-level``.
1169
1170
1171 math_output
1172 ~~~~~~~~~~~
1173 The format of mathematical content (`"math" directive`_ and role) in
1174 the output document. Supported values are (case insensitive):
1175
1176 HTML:
1177   Format math in standard HTML enhanced by CSS rules.
1178   Requires the ``math.css`` stylesheet (in the system
1179   `stylesheet directory <stylesheet_dirs [html writers]_>`__)
1180
1181   A `stylesheet_path <stylesheet_path [html writers]_>`__
1182   can be appended after whitespace. The specified
1183   stylesheet(s) will only be referenced or embedded if required
1184   (i.e. if there is mathematical content in the document).
1185
1186 MathML:
1187   Embed math content as presentational MathML_.
1188
1189   Self-contained documents (no JavaScript, no external downloads).
1190   MathML is part of the HTML5 standard [#mathml-in-html4]_ and
1191   `supported by all major browsers`__ (since January 2023 also by Chrome).
1192
1193   .. [#mathml-in-html4]
1194     With the "html4css1" writer, the resulting HTML document does
1195     not validate, as there is no DTD for `MathML + XHTML Transitional`.
1196     However, MathML-enabled browsers will render it fine.
1197
1198   Docutil's latex2mathml converter supports a considerable
1199   `subset of LaTeX math syntax`__.
1200
1201   An external converter can be appended after whitespace, e.g.,
1202   ``--math-output="MathML blahtexml"``:
1203
1204   .. class:: run-in narrow
1205
1206   :blahtexml_: Fast conversion, support for many symbols and environments,
1207                but no "align" (or other equation-aligning) environment. (C++)
1208   :LaTeXML_:   Comprehensive macro support but **very** slow. (Perl)
1209   :TtM_:       No "matrix", "align" and  "cases" environments.
1210                Support may be removed.
1211   :Pandoc_:    Comprehensive macro support, fast, but a large install size.
1212                (Haskell)
1213
1214   __ https://developer.mozilla.org/en-US/docs/Web/MathML#browser_compatibility
1215   __ ../ref/rst/mathematics.html
1216
1217 MathJax:
1218   Format math for display with MathJax_, a JavaScript-based math rendering
1219   engine.
1220
1221   :Pro: Works across multiple browsers and platforms.
1222         Large set of `supported LaTeX math commands and constructs`__
1223   :Con: Rendering requires JavaScript and an Internet connection or local
1224         MathJax installation.
1225
1226   __ http://docs.mathjax.org/en/latest/input/tex/macros/index.html
1227
1228   A URL pointing to a MathJax library should be appended after whitespace.
1229   A warning is given if this is missing.
1230
1231   * It is recommended to install__ the MathJax library on the same
1232     server as the rest of the deployed site files.
1233
1234     __ https://www.mathjax.org/#installnow
1235
1236     Example: Install the library at the top level of the web
1237     server’s hierarchy in the directory ``MathJax`` and set::
1238
1239       math-output: mathjax /MathJax/MathJax.js
1240
1241   * The easiest way to use MathJax is to link directly to a public
1242     installation. In that case, there is no need to install MathJax locally.
1243
1244     Downside: Downloads JavaScript code from a third-party site --- opens
1245     the door to cross-site scripting attacks!
1246
1247     Example: MathJax `getting started`__ documentation uses::
1248
1249       math-output: mathjax
1250          https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
1251
1252     See https://www.jsdelivr.com/ for details and terms of use.
1253
1254     __ https://www.mathjax.org/#gettingstarted
1255
1256   * Use a local MathJax installation on the *client* machine, e.g.::
1257
1258       math-output: MathJax file:/usr/share/javascript/mathjax/MathJax.js
1259
1260     This is the fallback if no URL is specified.
1261
1262 LaTeX:
1263   Include literal LaTeX code.
1264
1265   The failsafe fallback.
1266
1267 :Default: writer dependent (see `[html4css1 writer]`_, `[html5 writer]`_).
1268 :Option:  ``--math-output``.
1269
1270 .. _MathJax: http://www.mathjax.org/
1271 .. _MathML: https://www.w3.org/TR/MathML/
1272 .. _blahtexml: http://gva.noekeon.org/blahtexml/
1273 .. _LaTeXML: http://dlmf.nist.gov/LaTeXML/
1274 .. _TtM: http://hutchinson.belmont.ma.us/tth/mml/
1275 .. _Pandoc: https://pandoc.org/
1276
1277
1278 .. _stylesheet:
1279 .. _stylesheet [html writers]:
1280
1281 stylesheet
1282 ~~~~~~~~~~
1283 List of CSS stylesheet URLs  (comma-separated_). Used verbatim.
1284
1285 Overrides also stylesheet_path_. [#override]_
1286 See also `stylesheet [latex writers]`_.
1287
1288 *Default*: empty list.  *Option*: ``--stylesheet``.
1289
1290
1291 .. _stylesheet_dirs:
1292 .. _stylesheet_dirs [html writers]:
1293
1294 stylesheet_dirs
1295 ~~~~~~~~~~~~~~~
1296 List of directories where stylesheets can be found (comma-separated_).
1297 Used by the stylesheet_path_ setting when resolving relative path arguments.
1298
1299 See also `stylesheet_dirs [latex writers]`_.
1300
1301 Note: This setting defines a "search path" (similar to the PATH variable for
1302 executables). However, the term "path" is already used in the
1303 stylesheet_path_ setting with the meaning of a file location.
1304
1305 :Default: the working directory of the process at launch
1306           and the directory with default stylesheet files
1307           (writer and installation specific).
1308           Use the ``--help`` option to get the exact value.
1309 :Option:  ``--stylesheet-dirs``.
1310
1311
1312 .. _stylesheet_path:
1313 .. _stylesheet_path [html writers]:
1314
1315 stylesheet_path
1316 ~~~~~~~~~~~~~~~
1317 List of paths to CSS stylesheets (comma-separated_). Relative paths are
1318 expanded if a matching file is found in the stylesheet_dirs__.
1319 If embed_stylesheet__ is False, paths are rewritten relative to
1320 the output_ file (if specified) or the current work directory.
1321
1322 See also `stylesheet_path [latex writers]`_.
1323
1324 Overrides also stylesheet_. [#override]_
1325 Pass an empty string (to either "stylesheet" or "stylesheet_path") to
1326 deactivate stylesheet inclusion.
1327
1328 :Default: writer dependent (see `[html4css1 writer]`_,
1329           `[html5 writer]`_, `[pep_html writer]`_).
1330 :Option:  ``--stylesheet-path``.
1331
1332 __ `embed_stylesheet [html writers]`_
1333 __ `stylesheet_dirs [html writers]`_
1334
1335
1336 .. _table_style [html writers]:
1337
1338 table_style
1339 ~~~~~~~~~~~
1340 Class value(s) added to all tables_.
1341 See also `table_style [latex writers]`_.
1342
1343 The default CSS sylesheets define:
1344
1345 :borderless: no borders around table cells,
1346 :align-left, align-center, align-right: align table.
1347
1348 The HTML5 stylesheets also define:
1349
1350 :booktabs:
1351     Only lines above and below the table and a thin line after the head.
1352 :captionbelow:
1353     Place the table caption below the table (new in Docutils 0.17).
1354
1355 In addition, the HTML writers process:
1356
1357 :colwidths-auto:
1358     Delegate the determination of table column widths to the back-end
1359     (leave out the ``<colgroup>`` column specification).
1360     Overridden by the "widths" option of the `"table" directive`_.
1361 :colwidths-grid:
1362     Write column widths determined from the source to the HTML file.
1363     Overridden by the "widths" option of the `"table" directive`_.
1364
1365 *Default*: "".  *Option*: ``--table-style``.
1366
1367
1368 .. _template [html writers]:
1369
1370 template
1371 ~~~~~~~~
1372 Path [#pwd]_ to template file, which must be encoded in UTF-8.
1373 See also `template [latex writers]`_.
1374
1375 :Default: "template.txt" in the writer's directory (installed automatically)
1376           For the exact machine-specific path, use the ``--help`` option).
1377 :Option:  ``--template``.
1378
1379
1380 .. _xml_declaration [html writers]:
1381
1382 xml_declaration
1383 ~~~~~~~~~~~~~~~
1384 Prepend an XML declaration.
1385 See also `xml_declaration [docutils_xml writer]`_.
1386
1387 .. Caution:: The XML declaration carries text encoding information.  If the
1388    encoding is not UTF-8 or ASCII and the XML declaration is missing,
1389    standard XML tools may be unable to read the generated XHTML.
1390
1391 :Default: writer dependent.
1392 :Options: ``--xml-declaration``, ``--no-xml-declaration``.
1393
1394
1395 [html4css1 writer]
1396 ~~~~~~~~~~~~~~~~~~
1397 The `HTML4/CSS1 Writer`_ generates output that conforms to the
1398 `XHTML 1 Transitional`_ specification.
1399 It shares all settings defined in the `[html writers]`_
1400 `configuration section`_.
1401
1402
1403 Writer Specific Defaults
1404 """"""""""""""""""""""""
1405 .. class:: run-in narrow
1406
1407 :`initial_header_level`_:                               1 (for "<h1>").
1408 :`math_output`_:                                        "HTML math.css".
1409 :`stylesheet_path <stylesheet_path [html writers]_>`__: "html4css1.css".
1410 :`xml_declaration <xml_declaration [html writers]_>`__: True.
1411
1412 .. _HTML4/CSS1 Writer: html.html#html4css1
1413 .. _XHTML 1 Transitional: https://www.w3.org/TR/xhtml1/
1414
1415
1416 field_name_limit
1417 """"""""""""""""
1418 The maximum length (in characters) for one-column `field names`_. Longer
1419 field names will span an entire row of the table used to render the field
1420 list.  0 indicates "no limit".  See also option_limit_.
1421
1422 *Default*: 14.  *Option*: ``--field-name-limit``.
1423
1424
1425 option_limit
1426 """"""""""""
1427 The maximum length (in characters) for one-column options in `option lists`_.
1428 Longer options will span an entire row of the table used to render
1429 the option list.  0 indicates "no limit".
1430 See also field_name_limit_.
1431
1432 *Default*: 14.  *Option*: ``--option-limit``.
1433
1434
1435 [html5 writer]
1436 ~~~~~~~~~~~~~~
1437 The `HTML5 Writer`_ generates valid XML that is compatible with `HTML5`_.
1438 It shares all settings defined in the `[html writers]`_
1439 `configuration section`_.
1440
1441 New in Docutils 0.13.
1442
1443 .. _HTML5 Writer: html.html#html5-polyglot
1444 .. _HTML5: https://www.w3.org/TR/2014/REC-html5-20141028/
1445
1446
1447 Writer Specific Defaults
1448 """"""""""""""""""""""""
1449 .. class:: run-in narrow
1450
1451 :initial_header_level_:  2 (reserve <h1> for the `document title`_). [#]_
1452 :`math_output`_:         "MathML" (changed in Docutils 0.22).
1453 :`stylesheet_path <stylesheet_path [html writers]_>`__:
1454   "minimal.css, plain.css".
1455 :`xml_declaration <xml_declaration [html writers]_>`__:  False.
1456
1457 .. [#] Documents without (visible) document title may have <h2> as highest
1458    heading level, which is not recommended but valid (cf. "`Headings and
1459    outlines`__" in the HTML Standard). The default will change to None
1460    (<h2> if there is a document title, else <h1>) in Docutils 1.0.
1461
1462 __ https://html.spec.whatwg.org/multipage/sections.html
1463    #headings-and-outlines-2
1464
1465 image_loading
1466 """""""""""""
1467 Indicate at which point images should be loaded.
1468 Overridden by the `"image" directive`_'s ``:loading:`` option.
1469
1470 Supported values:
1471
1472 :embed: Embed still images into the HTML document
1473         (ignored for videos).
1474 :link:  Refer to images in the HTML document (default).
1475 :lazy:  Refer to images. Additionally specify the
1476         `lazy loading attribute`_ to defer fetching the image.
1477
1478 *Default*: "link".  *Option*: ``--image-loading``.
1479
1480 New in Docutils 0.18.
1481
1482 .. _lazy loading attribute: https://html.spec.whatwg.org/multipage/
1483     urls-and-fetching.html#lazy-loading-attributes
1484
1485 section_self_link
1486 """""""""""""""""
1487 Append an empty anchor element with a ``href`` to the section to
1488 section headings. See ``responsive.css`` for an example how this can be
1489 styled to show a symbol allowing users to copy the section's URL.
1490
1491 :Default: False.
1492 :Options: ``--section-self-link``, ``--no-section-self-link``.
1493
1494 New in Docutils 0.18.
1495
1496
1497 [pep_html writer]
1498 ~~~~~~~~~~~~~~~~~
1499 The PEP/HTML Writer derives from the HTML4/CSS1 Writer, and shares
1500 all settings defined in the `[html writers]`_ and `[html4css1 writer]`_
1501 `configuration sections`_.
1502
1503 Writer Specific Defaults
1504 """"""""""""""""""""""""
1505 .. class:: run-in narrow
1506
1507 :`initial_header_level`_:  1 (for "<h1>").
1508 :`stylesheet_path <stylesheet_path [html writers]_>`__:  "pep.css".
1509 :`template <template [html writers]_>`__:
1510   ``docutils/writers/pep_html/template.txt`` in the installation directory.
1511   For the exact machine-specific path, use the ``--help`` option.
1512
1513 no_random
1514 """""""""
1515 Do not use a random banner image.  Mainly used to get predictable
1516 results when testing.
1517
1518 *Default*: None (use random banner).  *Options*: ``--no-random`` (hidden).
1519
1520 pep_home
1521 """"""""
1522 Home URL prefix for PEPs.
1523
1524 *Default*: "." (current directory).  *Option*: ``--pep-home``.
1525
1526 python_home
1527 """""""""""
1528 Python's home URL.
1529
1530 *Default*: "https://www.python.org".  *Option*: ``--python-home``.
1531
1532
1533 [s5_html writer]
1534 ~~~~~~~~~~~~~~~~
1535 The S5/HTML Writer derives from the HTML4/CSS1 Writer, and shares
1536 all settings defined in the `[html writers]`_ and `[html4css1 writer]`_
1537 `configuration sections`_.
1538
1539 Writer Specific Defaults
1540 """"""""""""""""""""""""
1541 .. class:: run-in narrow
1542
1543 :compact_lists_:  disable compact lists.
1544 :template__:      ``docutils/writers/s5_html/template.txt`` in the
1545                   installation directory.  For the exact machine-specific
1546                   path, use the ``--help`` option.
1547
1548 __ `template [html writers]`_
1549
1550
1551 hidden_controls
1552 """""""""""""""
1553 Auto-hide the presentation controls in slideshow mode, or keep
1554 them visible at all times.
1555
1556 :Default: True (auto-hide).
1557 :Options: ``--hidden-controls``, ``--visible-controls``.
1558
1559 current_slide
1560 """""""""""""
1561 Enable or disable the current slide indicator ("1/15").
1562
1563 :Default: None (disabled).
1564 :Options: ``--current-slide``, ``--no-current-slide``.
1565
1566 overwrite_theme_files
1567 """""""""""""""""""""
1568 Allow or prevent the overwriting of existing theme files in the
1569 ``ui/<theme>`` directory.  This has no effect if "theme_url_" is
1570 used.
1571
1572 :Default: None (keep existing theme files).
1573 :Options: ``--keep-theme-files``, ``--overwrite-theme-files``.
1574
1575 theme
1576 """""
1577 Name of an installed S5 theme, to be copied into a ``ui/<theme>``
1578 subdirectory, beside the destination file (output HTML).  Note
1579 that existing theme files will not be overwritten; the existing
1580 theme directory must be deleted manually.
1581 Overrides also theme_url_. [#override]_
1582
1583 *Default*: "default".  *Option*: ``--theme``.
1584
1585 theme_url
1586 """""""""
1587 The URL of an S5 theme directory.  The destination file (output
1588 HTML) will link to this theme; nothing will be copied.
1589 Overrides also theme_. [#override]_
1590
1591 *Default*: None.  *Option*: ``--theme-url``.
1592
1593 view_mode
1594 """""""""
1595 The initial view mode, either "slideshow" or "outline".
1596
1597 *Default*: "slidewhow".  *Option*: ``--view-mode``.
1598
1599
1600
1601 [latex writers]
1602 ----------------
1603
1604 Common settings for the `LaTeX writers`_
1605 `[latex2e writer]`_ and `[xetex writer]`_.
1606
1607 .. _LaTeX writers: latex.html
1608
1609
1610 .. _attribution [latex writers]:
1611
1612 attribution
1613 ~~~~~~~~~~~
1614 Format for `block quote`_ attributions: one of "dash" (em-dash
1615 prefix), "parentheses"/"parens", or "none".
1616 See also `attribution  [html writers]`_.
1617
1618 *Default*: "dash".  *Option*: ``--attribution``.
1619
1620 compound_enumerators
1621 ~~~~~~~~~~~~~~~~~~~~
1622 Enable or disable compound enumerators for nested `enumerated lists`_
1623 (e.g. "1.2.a.ii").
1624
1625 :Default: None (disabled).
1626 :Options: ``--compound-enumerators``, ``--no-compound-enumerators``.
1627
1628 documentclass
1629 ~~~~~~~~~~~~~
1630 Specify LaTeX documentclass.
1631
1632 *Default*: "article".  *Option*: ``--documentclass``.
1633
1634 documentoptions
1635 ~~~~~~~~~~~~~~~
1636 Specify document options.  Multiple options can be given, separated by
1637 commas.
1638
1639 *Default*: "a4paper".  *Option*: ``--documentoptions``.
1640
1641
1642 docutils_footnotes
1643 ~~~~~~~~~~~~~~~~~~
1644 Use the Docutils-specific macros ``\DUfootnote`` and
1645 ``\DUfootnotetext`` for footnotes_.
1646
1647 TODO: The alternative, "latex_footnotes" is not implemented yet.
1648
1649 *Default*: True.  *Option*: ``--docutils-footnotes``.
1650
1651
1652 .. _embed_stylesheet [latex writers]:
1653
1654 embed_stylesheet
1655 ~~~~~~~~~~~~~~~~
1656 Embed the stylesheet(s) in the header of the output file.  The
1657 stylesheets must be accessible during processing.  Currently, this
1658 fails if the file is not available via the given path (i.e. the
1659 file is *not* searched in the `TeX input path`_).
1660 See also `embed_stylesheet [html writers]`_.
1661
1662 :Default: False (link to stylesheet).
1663 :Options: ``--embed-stylesheet``, ``--link-stylesheet``.
1664
1665
1666 .. _footnote_references [latex writers]:
1667
1668 footnote_references
1669 ~~~~~~~~~~~~~~~~~~~
1670 Format for `footnote references`_: one of "superscript" or "brackets".
1671 See also `footnote_references [html writers]`_.
1672
1673 Overrides also trim_footnote_reference_space_,
1674 if the parser supports this option. [#override]_
1675
1676 *Default*: "superscript".  *Option*: ``--footnote-references``.
1677
1678
1679 graphicx_option
1680 ~~~~~~~~~~~~~~~
1681 LaTeX graphicx package option.
1682
1683 Possible values are "dvips", "pdftex", "dvipdfmx".
1684
1685 *Default*: "".  *Option*: ``--graphicx-option``.
1686
1687 hyperlink_color
1688 ~~~~~~~~~~~~~~~
1689 Color of any hyperlinks embedded in text.
1690
1691 Special values:
1692
1693 .. class:: run-in narrow
1694
1695 :"0" or "false": disables coloring of links
1696                  (links will be marked by red boxes that are not printed).
1697 :"black":        results in “invisible“ links.
1698
1699 Set hyperref_options_ to "draft" to completely disable hyperlinking.
1700
1701 *Default*: "blue".  *Option*: ``--hyperlink-color``.
1702
1703 hyperref_options
1704 ~~~~~~~~~~~~~~~~
1705 Options for the `hyperref TeX package`_.
1706
1707 If hyperlink_color_ is not "false", the expansion of ::
1708
1709   'colorlinks=true,linkcolor=%s,urlcolor=%s' % (
1710       hyperlink_color, hyperlink_color)
1711
1712 is prepended.
1713
1714 *Default*: "".   *Option*: ``--hyperref-options``.
1715
1716 .. _hyperref TeX package: http://tug.org/applications/hyperref/
1717
1718
1719 latex_preamble
1720 ~~~~~~~~~~~~~~
1721 LaTeX code that will be inserted in the document preamble.
1722 Can be used to load packages with options or (re-) define LaTeX
1723 macros without writing a custom style file.
1724
1725 :Default: writer dependent (see `[latex2e writer]`_, `[xetex writer]`_).
1726 :Option:  ``--latex-preamble``.
1727
1728
1729 legacy_class_functions
1730 ~~~~~~~~~~~~~~~~~~~~~~
1731 Use legacy functions ``\DUtitle`` and ``\DUadmonition`` with a
1732 comma-separated list of class values as optional argument. If `False`, class
1733 values are handled with wrappers and admonitions use the ``DUadmonition``
1734 environment. See `Generating LaTeX with Docutils`__ for details.
1735
1736 :Default: False (default changed in Docutils 0.18).
1737 :Options: ``--legacy-class-functions``, ``--new-class-functions``.
1738
1739 New in Docutils 0.17
1740
1741 __ latex.html#classes
1742
1743
1744 legacy_column_widths
1745 ~~~~~~~~~~~~~~~~~~~~
1746 Use "legacy algorithm" to determine table column widths (for backwards
1747 compatibility).
1748
1749 The new algorithm limits the table width to the text width or specified
1750 table width and keeps the ratio of specified column widths.
1751
1752 Custom table and/or column widths can be set with the respective options
1753 of the `"table" directive`_. See also `Generating LaTeX with Docutils`__.
1754
1755 :Default: True (will change to False in Docutils 1.0).
1756 :Options: ``--legacy-column-widths``, ``--new-column-widths``.
1757
1758 New in Docutils 0.18.
1759
1760 __ latex.html#table-style
1761
1762
1763 literal_block_env
1764 ~~~~~~~~~~~~~~~~~
1765 Environment for `literal blocks`_. Used when the block does not contain
1766 inline elements. [#]_
1767
1768 The values "lstlisting", "listing", "verbatim", "Verbatim", and
1769 "verbatimtab" work out of the box; required LaTeX package are
1770 automatically loaded.
1771
1772 :Default: "" (use "alltt" with quoting of whitespace and special chars).
1773 :Option:  ``--literal-block-env``.
1774
1775 .. [#] A <literal-block> element originating from a `"parsed-literal"`_ or
1776    `"code"`_ directive may contain inline elements. LaTeX' verbatim-like
1777    environments cannot be used in this case.
1778
1779
1780 reference_label
1781 ~~~~~~~~~~~~~~~
1782 Per default the LaTeX writer uses ``\hyperref`` for `hyperlink
1783 references`_ to internal__ or implicit__ targets.
1784 Specify an alternative reference command name, e.g., "ref" or "pageref"
1785 to get the section number or the page number as reference text.
1786
1787 .. Caution::
1788    * Drops the original reference text.
1789    * Experimental. Not sufficiently tested.
1790    * Fails, e.g., with section numbering by Docutils (cf. sectnum_xform_)
1791      or tables without caption.
1792
1793 .. admonition:: Provisional
1794
1795    To be replaced by a dedicated `interpreted text role`_ for references
1796    (cf. TODO__).
1797
1798 *Default*: "" (use ``\hyperref``).  *Option*: ``--reference-label``.
1799
1800 __ ../ref/rst/restructuredtext.html#internal-hyperlink-targets
1801 __ ../ref/rst/restructuredtext.html#implicit-hyperlink-targets
1802 __ ../dev/todo.html#object-numbering-and-object-references
1803 .. _hyperlink references: ../ref/rst/restructuredtext.html#hyperlink-references
1804 .. _interpreted text role: ../ref/rst/restructuredtext.html#interpreted-text
1805
1806 section_enumerator_separator
1807 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1808 The separator between section number prefix and enumerator for
1809 compound enumerated lists (see `compound_enumerators`_).
1810
1811 Generally it isn't recommended to use both, numbered sub-sections and
1812 nested enumerated lists with compound enumerators.  This setting avoids
1813 ambiguity in the situation where a section "1" has a list item
1814 enumerated "1.1", and subsection "1.1" has list item "1".  With a
1815 separator of ".", these both would translate into a final compound
1816 enumerator of "1.1.1".  With a separator of "-", we get the
1817 unambiguous "1-1.1" and "1.1-1".
1818
1819 *Default*: "-".  *Option*: ``--section-enumerator-separator``.
1820
1821 section_prefix_for_enumerators
1822 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1823 Enable or disable section ("." subsection ...) prefixes for
1824 compound enumerators.  This has no effect unless
1825 `compound_enumerators`_ are enabled.
1826
1827 :Default: None (disabled).
1828 :Options: ``--section-prefix-for-enumerators``,
1829   ``--no-section-prefix-for-enumerators``.
1830
1831
1832 .. _stylesheet [latex writers]:
1833
1834 stylesheet
1835 ~~~~~~~~~~
1836 List of style files (comma-separated_). Used verbatim
1837 (under Windows, path separators are normalized to forward slashes).
1838 Overrides also stylesheet_path__. [#override]_
1839 See also `stylesheet [html writers]`_.
1840
1841 If `embed_stylesheet`__ is False (default), the stylesheet files are
1842 referenced with ``\usepackage`` (values with extension ``.sty`` or no
1843 extension) or ``\input`` (any other extension).
1844 LaTeX will search the specified files in the `TeX input path`_.
1845
1846 *Default*: empty list.  *Option*: ``--stylesheet``.
1847
1848 __ `stylesheet_path [latex writers]`_
1849 __ `embed_stylesheet [latex writers]`_
1850 .. _TeX input path: https://texfaq.org/FAQ-tds
1851
1852
1853 .. _stylesheet_dirs [latex writers]:
1854
1855 stylesheet_dirs
1856 ~~~~~~~~~~~~~~~
1857 List of directories where stylesheets can be found (comma-separated_).
1858 Used by the stylesheet_path__ setting.
1859
1860 Note: This setting defines a "search path" (similar to the PATH variable
1861 for executables). However, the term "path" is already used in the
1862 stylesheet_path__ setting with the meaning of a file location.
1863
1864 :Default: the working directory of the process at launch.
1865 :Option:  ``--stylesheet-dirs``.
1866
1867 __
1868 __ `stylesheet_path [latex writers]`_
1869
1870
1871 .. _stylesheet_path [latex writers]:
1872
1873 stylesheet_path
1874 ~~~~~~~~~~~~~~~
1875 List of style files (comma-separated_). Relative paths are expanded if a
1876 matching file is found in the stylesheet_dirs__.
1877 If embed_stylesheet__ is False, paths are rewritten relative to
1878 the output file (if output_ or `\<destination>`_ are specified)
1879 or the current work directory.
1880 Overrides also stylesheet__. [#override]_
1881 See also `stylesheet_path [html writers]`_.
1882
1883 For files in the `TeX input path`_, the stylesheet__  option is recommended.
1884
1885 *Default*: empty list.  *Option*: ``--stylesheet-path``.
1886
1887 .. _<destination>: tools.html#usage-pattern
1888 __ `stylesheet_dirs [latex writers]`_
1889 __ `embed_stylesheet [latex writers]`_
1890 __
1891 __ `stylesheet [latex writers]`_
1892
1893
1894 .. _table_style [latex writers]:
1895
1896 table_style
1897 ~~~~~~~~~~~
1898 Specify the default style for tables_.
1899 See also `table_style [html writers]`_.
1900
1901 Supported values: "booktabs", "borderless", "colwidths-auto", and "standard".
1902 See `Generating LaTeX with Docutils`__ for details.
1903
1904 *Default*: "standard".  *Option*: ``--table-style``.
1905
1906 __ latex.html#table-style
1907
1908
1909 .. _template [latex writers]:
1910
1911 template
1912 ~~~~~~~~
1913 Path [#pwd]_ to template file, which must be encoded in UTF-8.
1914 See also `template [html writers]`_.
1915
1916 :Default: writer dependent (see `[latex2e writer]`_, `[xetex writer]`_).
1917 :Option:  ``--template``.
1918
1919 use_bibtex
1920 ~~~~~~~~~~
1921
1922 List of style and database(s) for the experimental `BibTeX` support
1923 (comma-separated_). Example::
1924
1925   --use-bibtex=unsrt,mydb1,mydb2
1926
1927 .. admonition:: Provisional
1928
1929    Name, values, and behaviour may change in future versions or the
1930    option may be removed.
1931
1932 *Default*: empty list (don't use BibTeX).  *Option* ``--use-bibtex``.
1933
1934 use_latex_abstract
1935 ~~~~~~~~~~~~~~~~~~
1936 Use LaTeX abstract environment for the document's abstract_.
1937
1938 *Default*: False.
1939 *Options*: ``--use-latex-abstract``, ``--topic-abstract``.
1940
1941 use_latex_citations
1942 ~~~~~~~~~~~~~~~~~~~
1943 Use ``\cite`` for citations_.
1944
1945 :Default: False (use simulation with figure-floats).
1946           The default will change in Docutils 1.0.
1947 :Options: ``--use-latex-citations``, ``--figure-citations``.
1948
1949 use_latex_docinfo
1950 ~~~~~~~~~~~~~~~~~
1951 Attach author and date to the `document title`_.
1952
1953 :Default: False (attach author and date to the `bibliographic fields`_).
1954 :Options: ``--use-latex-docinfo``, ``--use-docutils-docinfo``.
1955
1956 use_latex_toc
1957 ~~~~~~~~~~~~~
1958 Let LaTeX generate the `table of contents`_. Generates a ToC with page numbers.
1959 Usually LaTeX must be run twice to get the numbers correct.
1960
1961 *Default*: True.  *Options*: ``--use-latex-toc``, ``--use-docutils-toc``.
1962
1963 use_part_section
1964 ~~~~~~~~~~~~~~~~
1965 Add parts on top of the section hierarchy.
1966
1967 *Default*: False.  *Option*: ``--use-part-section``.
1968
1969 [latex2e writer]
1970 ~~~~~~~~~~~~~~~~
1971 The `LaTeX2e writer`_ generates a LaTeX source suited for compilation
1972 with 8-bit LaTeX (pdfTeX_). It shares all settings defined in the `[latex
1973 writers]`_ `configuration section`_.
1974
1975 .. _LaTeX2e writer: latex.html#latex2e-writer
1976 .. _pdfTeX: https://www.tug.org/applications/pdftex/
1977
1978
1979 Writer Specific Defaults
1980 """"""""""""""""""""""""
1981 .. class:: run-in narrow
1982
1983 :latex_preamble_: Load the "PDF standard fonts" (Times, Helvetica, Courier)::
1984
1985     \usepackage{mathptmx} % Times
1986     \usepackage[scaled=.90]{helvet}
1987     \usepackage{courier}
1988
1989 :template__:
1990   "default.tex" in the ``docutils/writers/latex2e/`` directory
1991   (installed automatically).
1992
1993   __ `template [latex writers]`_
1994
1995
1996 font_encoding
1997 """""""""""""
1998 String with `LaTeX font encoding`_.  Multiple encodings can be specified
1999 separated by commas. The last value becomes the document default.
2000
2001 *Default*: "T1".  *Option*: ``--font-encoding``.
2002
2003 .. _LaTeX font encoding: latex.html#font-encoding
2004
2005
2006 [xetex writer]
2007 ~~~~~~~~~~~~~~
2008 The `XeTeX writer`_ generates a LaTeX source suited for compilation with
2009 `XeTeX or LuaTeX`_. It derives from the latex2e writer, and shares all
2010 settings defined in the `[latex writers]`_ `configuration section`_.
2011
2012 .. _XeTeX writer: latex.html#xetex-writer
2013 .. _XeTeX or LuaTeX: https://texfaq.org/FAQ-xetex-luatex
2014
2015 Writer Specific Defaults
2016 """"""""""""""""""""""""
2017 .. class:: run-in narrow
2018
2019 :latex_preamble_:  Font setup for `Linux Libertine`_,::
2020
2021       % Linux Libertine (free, wide coverage, not only for Linux)
2022       \setmainfont{Linux Libertine O}
2023       \setsansfont{Linux Biolinum O}
2024       \setmonofont[HyphenChar=None]{DejaVu Sans Mono}
2025
2026   The optional argument ``HyphenChar=None`` to the monospace font
2027   prevents word hyphenation in literal text.
2028
2029 :template__: "xelatex.tex" in the ``docutils/writers/latex2e/`` directory
2030              (installed automatically).
2031
2032              .. TODO: show full path with ``--help`` (like in the HTML
2033                 writers) and add the following line: for the exact
2034                 machine-specific path, use the ``--help`` option).
2035
2036 .. _Linux Libertine: http://www.linuxlibertine.org/
2037 __ `template [latex writers]`_
2038
2039
2040 .. _ODF/ODT Writer:
2041
2042 [odf_odt writer]
2043 ----------------
2044
2045 The ODF/`ODT Writer`_ generates documents in the
2046 OpenDocument_ Text format (.odt).
2047
2048 The output_encoding_ setting is ignored, the output encoding is
2049 always "UTF-8".
2050
2051 .. _ODT Writer: odt.html
2052 .. _OpenDocument: https://en.wikipedia.org/wiki/OpenDocument
2053
2054 add-syntax_highlighting
2055 ~~~~~~~~~~~~~~~~~~~~~~~
2056 Add syntax highlighting in literal code blocks.
2057 See section "`Syntax highlighting`__" in the ODT Writer documentation
2058 for details.
2059
2060 :Default: False.
2061 :Options: ``--add-syntax-highlighting``, ``--no-syntax-highlighting``.
2062
2063 __ odt.html#syntax-highlighting
2064
2065 create_links
2066 ~~~~~~~~~~~~
2067 Create links.
2068
2069 *Default*: False.
2070 *Options*: ``--create-links``, ``--no-links``.
2071
2072 create_sections
2073 ~~~~~~~~~~~~~~~
2074 Create sections for headers.
2075
2076 :Default: True.
2077 :Options: ``--create-sections``, ``--no-sections``.
2078
2079 cloak_email_addresses
2080 ~~~~~~~~~~~~~~~~~~~~~
2081 Obfuscate email addresses to confuse harvesters while still
2082 keeping email links usable with standards-compliant browsers.
2083
2084 :Default: False.
2085 :Options: ``--cloak-email-addresses``, ``--no-cloak-email-addresses``.
2086
2087 custom_header
2088 ~~~~~~~~~~~~~
2089 Specify the contents of a custom header line.
2090 See section "`Custom header/footers`_" in the ODT Writer documentation
2091 for details.
2092
2093 *Default*: "" (no header).
2094 *Option*: ``--custom-odt-header``.
2095
2096 custom_footer
2097 ~~~~~~~~~~~~~
2098 Specify the contents of a custom footer line.
2099 See section "`Custom header/footers`_" in the ODT Writer documentation
2100 for details.
2101
2102 *Default*: "" (no footer).
2103 *Option*: ``--custom-odt-footer``.
2104
2105 .. _custom header/footers:
2106     odt.html#custom-header-footers-inserting-page-numbers-date-time-etc
2107
2108 endnotes_end_doc
2109 ~~~~~~~~~~~~~~~~
2110 Generate endnotes at end of document, not footnotes at bottom of page.
2111
2112 :Default: False.
2113 :Options: ``--endnotes-end-doc``, ``--no-endnotes-end-doc``.
2114
2115 generate_oowriter_toc
2116 ~~~~~~~~~~~~~~~~~~~~~
2117 Generate a native ODF table of contents, not a bullet list.
2118 See section "`Table of contents`__" in the ODT Writer documentation
2119 for details.
2120
2121 :Default: True.
2122 :Options: ``--generate-oowriter-toc``, ``--generate-list-toc``.
2123
2124 __ odt.html#table-of-contents
2125
2126 odf_config_file
2127 ~~~~~~~~~~~~~~~
2128 Path [#pwd]_ to a configuration/mapping file for additional ODF options.
2129 In particular, this file may contain a mapping of default style names to
2130 names used in the resulting output file.
2131 See section `How to use custom style names`__ in the
2132 ODT Writer documentation for details.
2133
2134 *Default*: None.
2135 *Option*: ``--odf-config-file``.
2136
2137 __ odt.html#how-to-use-custom-style-names
2138
2139 stylesheet
2140 ~~~~~~~~~~
2141 Path [#pwd]_ to a style file.  See section `Styles and Classes`_
2142 in the ODT Writer documentation for details.
2143
2144 :Default: "writers/odf_odt/styles.odt" in the installation directory.
2145 :Option:  ``--stylesheet``.
2146
2147 .. _styles and classes: odt.html#styles-and-classes
2148
2149 table_border_thickness
2150 ~~~~~~~~~~~~~~~~~~~~~~
2151 Specify the thickness of table borders in thousands of a centimetre.
2152 The `Table styles`__ section in the ODT Writer documentation describes
2153 alternatives for additional customisation of the table style.
2154
2155 *Default*: 35 (0.35 mm).
2156 *Option*: ``--table-border-thickness``.
2157
2158 __ odt.html#table-styles
2159
2160
2161 [pseudoxml writer]
2162 ------------------
2163
2164 detailed
2165 ~~~~~~~~~
2166 Pretty-print <#text> nodes.
2167
2168 *Default*: False.  *Option*: ``--detailed``.
2169
2170
2171 [applications]
2172 ==============
2173
2174 Some `front end tools`_ provide additional settings.
2175
2176
2177 .. _buildhtml:
2178
2179 [buildhtml application]
2180 -----------------------
2181
2182 buildhtml.py_ generates HTML documents from reStructuredText source
2183 files in a set of directories and their subdirectories.
2184 All visited directories are scanned for "docutils.conf" files which are
2185 parsed after the standard configuration files. Path settings [#pwd]_ in
2186 these files are resolved relative to the respective directory.
2187
2188 The output_ setting is ignored.
2189
2190 dry_run
2191 ~~~~~~~
2192 Do not process files, show files that would be processed.
2193
2194 *Default*: False (process files).  *Option*: ``--dry-run``.
2195
2196 ignore
2197 ~~~~~~
2198 List of glob-style patterns [#globbing]_ (colon-separated_).
2199 Source files with matching filename are silently ignored.
2200 Values are appended. [#append-values]_
2201
2202 *Default*: empty list.  *Option*: ``--ignore``.
2203
2204 prune
2205 ~~~~~
2206 List of glob-style patterns [#globbing]_ (colon-separated_).
2207 Matching directories are skipped. Values are appended. [#append-values]_
2208
2209 Patterns are expanded similar to path settings [#pwd]_ and matched
2210 against the absolute path of to-be-processed directories.
2211 Example: a directory is pruned if it contains a "docutils.conf" file
2212 with the lines ::
2213
2214   [buildhtml application]
2215   prune: '.'
2216
2217 The default patterns skip auxiliary directories from Python or
2218 popular version control tools anywhere [#]_.
2219
2220 :Default: ``/*/.hg:/*/.bzr:/*/.git:/*/.svn:/*/.venv:/*/__pycache__``.
2221 :Option:  ``--prune``.
2222
2223 .. [#] The leading "/" prevents expansion with `pwd`;
2224        ``fnmatch('/*')`` matches any absolute path.
2225
2226 recurse
2227 ~~~~~~~
2228 Recursively scan subdirectories.
2229
2230 *Default*: True.  *Options*: ``--recurse``, ``--local``.
2231
2232 sources
2233 ~~~~~~~
2234 List of glob-style [#globbing]_ patterns (colon-separated_).
2235 Files with matching filename are treated as source documents.
2236 Values in configuration files overwrite the default and are
2237 overwritten by the command line option.
2238
2239 *Default*: ``*.rst:*.txt``.  *Option*: ``--rst-sources``.
2240
2241 New in Docutils 0.21.
2242
2243 silent
2244 ~~~~~~
2245 Work silently (no progress messages).
2246 Independent of report_level_.
2247
2248 *Default*: None (show progress).  *Option*: ``--silent``.
2249
2250 .. _html_writer:
2251 .. _writer [buildhtml application]:
2252
2253 writer
2254 ~~~~~~
2255 `HTML writer`_ version. One of "html", "html4", "html5".
2256
2257 :Default: "html" (use Docutils' `default HTML writer`_).
2258 :Option:  ``--writer``
2259
2260 New in 0.17. Obsoletes the ``html_writer`` option.
2261
2262 .. _HTML writer: html.html
2263 .. _default HTML writer: html.html#html
2264
2265 .. [#globbing] Pattern matching is done with the `fnmatch module`_.
2266    It resembles shell-style globbing, but without special treatment
2267    of path separators and '.' (in contrast__ to the `glob module`_ and
2268    `pathlib.PurePath.match()`_).
2269    For example, "``/*.py``" matches "/a/b/c.py".
2270
2271    Provisional: may use `pathlib.PurePath.match()` once this supports "**".
2272
2273 .. _fnmatch module:
2274     https://docs.python.org/3/library/fnmatch.html#module-fnmatch
2275 .. _glob module:
2276     https://docs.python.org/3/library/glob.html#module-glob
2277 .. _pathlib.PurePath.match():
2278     https://docs.python.org/3/library/pathlib.html#pathlib.PurePath.match
2279 __ https://github.com/python/cpython/issues/106747
2280
2281
2282 [docutils application]
2283 --------------------------
2284
2285 Docutils' `generic front end`_ tool allows combining “reader”, “parser”,
2286 and “writer” components from the Docutils package or 3rd party plug-ins.
2287
2288 | New in 0.17. Config file support added in 0.18. Renamed in 0.19
2289   (the old section name "docutils-cli application" is kept as alias).
2290 | Support for reader/parser import names added in 0.19.
2291
2292 .. _generic front end: tools.html#generic-command-line-front-end
2293
2294 reader
2295 ~~~~~~
2296 Reader component name.
2297 One of "standalone", "pep", or the import name of a plug-in reader module.
2298
2299 *Default*: "standalone".
2300 *Option*: ``--reader``
2301
2302 parser
2303 ~~~~~~
2304 Parser component name.
2305 Either "`rst <[restructuredtext parser]_>`__" (default),
2306 "`xml <[xml parser]_>`__", or the import name of a plug-in parser module.
2307
2308 Parsers for CommonMark_ known to work with Docutils include
2309 "`pycmark <[pycmark parser]_>`__", "`myst <[myst parser]_>`__",
2310 and "`recommonmark <[recommonmark parser]_>`__".
2311
2312 *Default*: "rst".
2313 *Option*: ``--parser``
2314
2315 .. _CommonMark: https://spec.commonmark.org/current/
2316
2317
2318 .. _writer [docutils application]:
2319
2320 writer
2321 ~~~~~~
2322 Writer component name.
2323 One of "html", "html4", "html5", "latex", "xelatex", "odt", "xml",
2324 "pseudoxml", "manpage", "pep_html", "s5", an alias,
2325 or the import name of a plug-in writer module.
2326
2327 *Default*: "html5".
2328 *Option*: ``--writer``
2329
2330
2331 Other Settings
2332 ==============
2333
2334 Command-Line Only
2335 -----------------
2336
2337 These settings are only effective as command-line options; setting
2338 them in configuration files has no effect.
2339
2340 config
2341 ~~~~~~
2342 Path to an additional configuration file.
2343 The file is processed immediately (if it exists) with
2344 settings overriding defaults and earlier settings.
2345
2346 Filesystem path settings [#pwd]_ contained within the config file will be
2347 interpreted relative to the config file's location (*not* relative to the
2348 current working directory).
2349
2350 Multiple ``--config`` options may be specified;
2351 each will be processed in turn.
2352
2353 *Default*: None.  *Option*: ``--config``.
2354
2355
2356 Internal Settings
2357 -----------------
2358
2359 These settings are for internal use only; setting them in
2360 configuration files has no effect, and there are no corresponding
2361 command-line options.
2362
2363 _config_files
2364 ~~~~~~~~~~~~~
2365 List of paths of applied configuration files.
2366
2367 *Default*: None.  No command-line options.
2368
2369 _directories
2370 ~~~~~~~~~~~~
2371 (``buildhtml.py`` front end.)  List of paths to source
2372 directories, set from positional arguments.
2373
2374 *Default*: None (current working directory).  No command-line options.
2375
2376 _disable_config
2377 ~~~~~~~~~~~~~~~
2378 Prevent standard configuration files from being read.
2379 For command-line use, set the DOCUTILSCONFIG_ variable.
2380
2381 :Default: None (config files enabled).  No command-line options.
2382
2383 _destination
2384 ~~~~~~~~~~~~
2385 Path to output destination, set from positional arguments.
2386
2387 *Default*: None (stdout).  No command-line options.
2388
2389 _source
2390 ~~~~~~~
2391 Path to input source, set from positional arguments.
2392
2393 *Default*: None (stdin).  No command-line options.
2394
2395 --------------------------------------------------------------------------
2396
2397 .. [#override] The overridden setting will automatically be set to
2398    ``None`` for command-line options and config file settings.  Client
2399    programs which specify defaults that override other settings must
2400    do the overriding explicitly, by assigning ``None`` to the other
2401    settings.
2402
2403 .. [#append-values] Some settings append values from the various
2404    sources to a list instead of overriding previous values.
2405    The corresponding command line options may be used more than once.
2406
2407 .. [#pwd] Filesystem path relative to the working directory of the
2408    process at launch.
2409    Exception: Path settings in configuration files specified by the
2410    config_ command line option or in directories visited by the
2411    buildhtml_ application are resolved relative to the directory of
2412    the respective configuration file.
2413
2414
2415 Old-Format Configuration Files
2416 ==============================
2417
2418 Formerly, Docutils configuration files contained a single "[options]"
2419 section only.  This was found to be inflexible, and in August 2003
2420 Docutils adopted the current component-based configuration file
2421 sections as described above.
2422 Up to version 2.0, Docutils will still recognize the old "[options]"
2423 section, but complain with a deprecation warning.
2424
2425 To convert existing config files, the easiest way is to change the
2426 section title: change "[options]" to "[general]".  Most settings
2427 haven't changed.  The only ones to watch out for are these:
2428
2429 =====================  =====================================
2430 Old-Format Setting     New Section & Setting
2431 =====================  =====================================
2432 pep_stylesheet         [pep_html writer] stylesheet
2433 pep_stylesheet_path    [pep_html writer] stylesheet_path
2434 pep_template           [pep_html writer] template
2435 =====================  =====================================
2436
2437 .. References
2438
2439 .. _Docutils Document Tree:
2440 .. _Document Tree: ../ref/doctree.html
2441
2442 .. _Docutils Runtime Settings:
2443 .. _runtime settings: ../api/runtime-settings.html
2444
2445 .. _Publisher Interface: ../api/publisher.html
2446
2447 .. RestructuredText Directives
2448 .. _"class" directive: ../ref/rst/directives.html#class
2449 .. _"code": ../ref/rst/directives.html#code
2450 .. _"csv-table": ../ref/rst/directives.html#csv-table
2451 .. _"image" directive: ../ref/rst/directives.html#image
2452 .. _"include": ../ref/rst/directives.html#include
2453 .. _"math" directive: ../ref/rst/directives.html#math
2454 .. _"parsed-literal": ../ref/rst/directives.html#parsed-literal
2455 .. _"raw":
2456 .. _"raw" directive: ../ref/rst/directives.html#raw
2457 .. _"sectnum" directive: ../ref/rst/directives.html#sectnum
2458 .. _"substitution": ../ref/rst/directives.html#substitution
2459 .. _"table" directive: ../ref/rst/directives.html#table
2460 .. _"title" directive: ../ref/rst/directives.html#metadata-document-title
2461 .. _table of contents: ../ref/rst/directives.html#table-of-contents
2462
2463 .. RestructuredText Markup Specification
2464 .. _abstract:
2465 .. _bibliographic field list:
2466 .. _bibliographic fields:
2467     ../ref/rst/restructuredtext.html#bibliographic-fields
2468 .. _block quote: ../ref/rst/restructuredtext.html#block-quotes
2469 .. _bullet lists: ../ref/rst/restructuredtext.html#bullet-lists
2470 .. _citations: ../ref/rst/restructuredtext.html#citations
2471 .. _document title: ../ref/rst/restructuredtext.html#document-title
2472 .. _enumerated lists: ../ref/rst/restructuredtext.html#enumerated-lists
2473 .. _field lists: ../ref/rst/restructuredtext.html#field-lists
2474 .. _field names: ../ref/rst/restructuredtext.html#field-names
2475 .. _footnotes: ../ref/rst/restructuredtext.html#footnotes
2476 .. _footnote references: ../ref/rst/restructuredtext.html#footnote-references
2477 .. _inline markup recognition rules:
2478     ../ref/rst/restructuredtext.html#inline-markup-recognition-rules
2479 .. _literal blocks: ../ref/rst/restructuredtext.html#literal-blocks
2480 .. _option lists: ../ref/rst/restructuredtext.html#option-lists
2481 .. _tables: ../ref/rst/restructuredtext.html#tables
2482
2483 .. _front end tools: tools.html
2484 .. _buildhtml.py: tools.html#buildhtml-py
2485
2486 .. _BCP 47: https://www.rfc-editor.org/rfc/bcp/bcp47.txt
2487 .. _Error Handlers:
2488     https://docs.python.org/3/library/codecs.html#error-handlers
2489 .. _ISO 639: http://www.loc.gov/standards/iso639-2/php/English_list.php
2490 .. _ISO 3166: http://www.iso.ch/iso/en/prods-services/iso3166ma/
2491     02iso-3166-code-lists/index.html
2492 .. _language tag: https://www.w3.org/International/articles/language-tags/