| Server IP : 82.148.16.210 / Your IP : 216.73.216.19 Web Server : nginx/1.29.5 System : Linux mail.sarafai.ru 6.1.0-43-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.162-1 (2026-02-08) x86_64 User : root ( 0) PHP Version : 7.4.33 Disable Function : pcntl_alarm,pcntl_fork,pcntl_waitpid,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wifcontinued,pcntl_wexitstatus,pcntl_wtermsig,pcntl_wstopsig,pcntl_signal,pcntl_signal_get_handler,pcntl_signal_dispatch,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,pcntl_sigtimedwait,pcntl_exec,pcntl_getpriority,pcntl_setpriority,pcntl_async_signals,pcntl_unshare, MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : OFF Directory : /proc/746/root/usr/share/doc/python3-docutils/docs/user/ |
Upload File : |
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>Docutils Configuration</title>
<meta name="author" content="David Goodger" />
<meta name="date" content="2022-06-17" />
<meta name="copyright" content="This document has been placed in the public domain." />
<link rel="stylesheet" href="../../css/html4css1.css" type="text/css" />
</head>
<body>
<div class="header">
<a class="reference external" href="https://docutils.sourceforge.io">Docutils</a> | <a class="reference external" href="../index.html">Overview</a> | <a class="reference external" href="../index.html#project-fundamentals">About</a> | <a class="reference external" href="../index.html#user">Users</a> | <a class="reference external" href="../index.html#ref">Reference</a> | <a class="reference external" href="../index.html#howto">Developers</a>
<hr class="header"/>
</div>
<div class="document" id="docutils-configuration">
<h1 class="title">Docutils Configuration</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>David Goodger</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference external" href="mailto:docutils-develop@lists.sourceforge.net">docutils-develop@lists.sourceforge.net</a></td></tr>
<tr><th class="docinfo-name">Revision:</th>
<td>9077</td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2022-06-17</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>This document has been placed in the public domain.</td></tr>
</tbody>
</table>
<!-- Minimal menu bar for inclusion in documentation sources
in ``docutils/docs/*/`` sub-diretories.
Attention: this is not a standalone document. -->
<div class="sidebar">
<p class="first sidebar-title">Docutils Security for Web Applications</p>
<p class="last">For details about securing web applications, please see <a class="reference external" href="../howto/security.html">Deploying
Docutils Securely</a>.</p>
</div>
<div class="contents topic" id="contents">
<p class="topic-title">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#configuration-files" id="toc-entry-1">Configuration Files</a></li>
<li><a class="reference internal" href="#configuration-file-syntax" id="toc-entry-2">Configuration File Syntax</a><ul>
<li><a class="reference internal" href="#example" id="toc-entry-3">Example</a></li>
</ul>
</li>
<li><a class="reference internal" href="#configuration-file-sections-entries" id="toc-entry-4">Configuration File Sections & Entries</a><ul>
<li><a class="reference internal" href="#general" id="toc-entry-5">[general]</a><ul>
<li><a class="reference internal" href="#auto-id-prefix" id="toc-entry-6">auto_id_prefix</a></li>
<li><a class="reference internal" href="#datestamp" id="toc-entry-7">datestamp</a></li>
<li><a class="reference internal" href="#debug" id="toc-entry-8">debug</a></li>
<li><a class="reference internal" href="#dump-internals" id="toc-entry-9">dump_internals</a></li>
<li><a class="reference internal" href="#dump-pseudo-xml" id="toc-entry-10">dump_pseudo_xml</a></li>
<li><a class="reference internal" href="#dump-settings" id="toc-entry-11">dump_settings</a></li>
<li><a class="reference internal" href="#dump-transforms" id="toc-entry-12">dump_transforms</a></li>
<li><a class="reference internal" href="#error-encoding" id="toc-entry-13">error_encoding</a></li>
<li><a class="reference internal" href="#error-encoding-error-handler" id="toc-entry-14">error_encoding_error_handler</a></li>
<li><a class="reference internal" href="#exit-status-level" id="toc-entry-15">exit_status_level</a></li>
<li><a class="reference internal" href="#expose-internals" id="toc-entry-16">expose_internals</a></li>
<li><a class="reference internal" href="#footnote-backlinks" id="toc-entry-17">footnote_backlinks</a></li>
<li><a class="reference internal" href="#generator" id="toc-entry-18">generator</a></li>
<li><a class="reference internal" href="#halt-level" id="toc-entry-19">halt_level</a></li>
<li><a class="reference internal" href="#id-prefix" id="toc-entry-20">id_prefix</a></li>
<li><a class="reference internal" href="#input-encoding" id="toc-entry-21">input_encoding</a></li>
<li><a class="reference internal" href="#input-encoding-error-handler" id="toc-entry-22">input_encoding_error_handler</a></li>
<li><a class="reference internal" href="#language-code" id="toc-entry-23">language_code</a></li>
<li><a class="reference internal" href="#output-encoding" id="toc-entry-24">output_encoding</a></li>
<li><a class="reference internal" href="#output-encoding-error-handler" id="toc-entry-25">output_encoding_error_handler</a></li>
<li><a class="reference internal" href="#record-dependencies" id="toc-entry-26">record_dependencies</a></li>
<li><a class="reference internal" href="#report-level" id="toc-entry-27">report_level</a></li>
<li><a class="reference internal" href="#sectnum-xform" id="toc-entry-28">sectnum_xform</a></li>
<li><a class="reference internal" href="#source-link" id="toc-entry-29">source_link</a></li>
<li><a class="reference internal" href="#source-url" id="toc-entry-30">source_url</a></li>
<li><a class="reference internal" href="#strict-visitor" id="toc-entry-31">strict_visitor</a></li>
<li><a class="reference internal" href="#strip-classes" id="toc-entry-32">strip_classes</a></li>
<li><a class="reference internal" href="#strip-comments" id="toc-entry-33">strip_comments</a></li>
<li><a class="reference internal" href="#strip-elements-with-classes" id="toc-entry-34">strip_elements_with_classes</a></li>
<li><a class="reference internal" href="#title" id="toc-entry-35">title</a></li>
<li><a class="reference internal" href="#toc-backlinks" id="toc-entry-36">toc_backlinks</a></li>
<li><a class="reference internal" href="#traceback" id="toc-entry-37">traceback</a></li>
<li><a class="reference internal" href="#warning-stream" id="toc-entry-38">warning_stream</a></li>
</ul>
</li>
<li><a class="reference internal" href="#parsers" id="toc-entry-39">[parsers]</a><ul>
<li><a class="reference internal" href="#file-insertion-enabled" id="toc-entry-40">file_insertion_enabled</a></li>
<li><a class="reference internal" href="#line-length-limit" id="toc-entry-41">line_length_limit</a></li>
<li><a class="reference internal" href="#raw-enabled" id="toc-entry-42">raw_enabled</a></li>
<li><a class="reference internal" href="#restructuredtext-parser" id="toc-entry-43">[restructuredtext parser]</a><ul>
<li><a class="reference internal" href="#character-level-inline-markup" id="toc-entry-44">character_level_inline_markup</a></li>
<li><a class="reference internal" href="#pep-references" id="toc-entry-45">pep_references</a></li>
<li><a class="reference internal" href="#pep-base-url" id="toc-entry-46">pep_base_url</a></li>
<li><a class="reference internal" href="#pep-file-url-template" id="toc-entry-47">pep_file_url_template</a></li>
<li><a class="reference internal" href="#rfc-references" id="toc-entry-48">rfc_references</a></li>
<li><a class="reference internal" href="#rfc-base-url" id="toc-entry-49">rfc_base_url</a></li>
<li><a class="reference internal" href="#smart-quotes" id="toc-entry-50">smart_quotes</a></li>
<li><a class="reference internal" href="#smartquotes-locales" id="toc-entry-51">smartquotes_locales</a></li>
<li><a class="reference internal" href="#syntax-highlight" id="toc-entry-52">syntax_highlight</a></li>
<li><a class="reference internal" href="#tab-width" id="toc-entry-53">tab_width</a></li>
<li><a class="reference internal" href="#trim-footnote-reference-space" id="toc-entry-54">trim_footnote_reference_space</a></li>
</ul>
</li>
<li><a class="reference internal" href="#myst-parser" id="toc-entry-55">[myst parser]</a></li>
<li><a class="reference internal" href="#pycmark-parser" id="toc-entry-56">[pycmark parser]</a></li>
<li><a class="reference internal" href="#recommonmark-parser" id="toc-entry-57">[recommonmark parser]</a></li>
</ul>
</li>
<li><a class="reference internal" href="#readers" id="toc-entry-58">[readers]</a><ul>
<li><a class="reference internal" href="#standalone-reader" id="toc-entry-59">[standalone reader]</a><ul>
<li><a class="reference internal" href="#docinfo-xform" id="toc-entry-60">docinfo_xform</a></li>
<li><a class="reference internal" href="#doctitle-xform" id="toc-entry-61">doctitle_xform</a></li>
<li><a class="reference internal" href="#sectsubtitle-xform" id="toc-entry-62">sectsubtitle_xform</a></li>
</ul>
</li>
<li><a class="reference internal" href="#pep-reader" id="toc-entry-63">[pep reader]</a></li>
</ul>
</li>
<li><a class="reference internal" href="#writers" id="toc-entry-64">[writers]</a><ul>
<li><a class="reference internal" href="#docutils-xml-writer" id="toc-entry-65">[docutils_xml writer]</a><ul>
<li><a class="reference internal" href="#doctype-declaration" id="toc-entry-66">doctype_declaration</a></li>
<li><a class="reference internal" href="#indents" id="toc-entry-67">indents</a></li>
<li><a class="reference internal" href="#newlines" id="toc-entry-68">newlines</a></li>
<li><a class="reference internal" href="#xml-declaration" id="toc-entry-69">xml_declaration</a></li>
</ul>
</li>
<li><a class="reference internal" href="#html-writers" id="toc-entry-70">[html writers]</a><ul>
<li><a class="reference internal" href="#attribution" id="toc-entry-71">attribution</a></li>
<li><a class="reference internal" href="#cloak-email-addresses" id="toc-entry-72">cloak_email_addresses</a></li>
<li><a class="reference internal" href="#compact-lists" id="toc-entry-73">compact_lists</a></li>
<li><a class="reference internal" href="#compact-field-lists" id="toc-entry-74">compact_field_lists</a></li>
<li><a class="reference internal" href="#embed-stylesheet" id="toc-entry-75">embed_stylesheet</a></li>
<li><a class="reference internal" href="#footnote-references" id="toc-entry-76">footnote_references</a></li>
<li><a class="reference internal" href="#initial-header-level" id="toc-entry-77">initial_header_level</a></li>
<li><a class="reference internal" href="#math-output" id="toc-entry-78">math_output</a></li>
<li><a class="reference internal" href="#stylesheet" id="toc-entry-79">stylesheet</a></li>
<li><a class="reference internal" href="#stylesheet-dirs" id="toc-entry-80">stylesheet_dirs</a></li>
<li><a class="reference internal" href="#stylesheet-path-1" id="toc-entry-81">stylesheet_path</a></li>
<li><a class="reference internal" href="#table-style" id="toc-entry-82">table_style</a></li>
<li><a class="reference internal" href="#template" id="toc-entry-83">template</a></li>
<li><a class="reference internal" href="#xml-declaration-1" id="toc-entry-84">xml_declaration</a></li>
<li><a class="reference internal" href="#html4css1-writer" id="toc-entry-85">[html4css1 writer]</a><ul>
<li><a class="reference internal" href="#writer-specific-defaults" id="toc-entry-86">Writer Specific Defaults</a></li>
<li><a class="reference internal" href="#field-name-limit" id="toc-entry-87">field_name_limit</a></li>
<li><a class="reference internal" href="#option-limit" id="toc-entry-88">option_limit</a></li>
</ul>
</li>
<li><a class="reference internal" href="#html5-writer" id="toc-entry-89">[html5 writer]</a><ul>
<li><a class="reference internal" href="#writer-specific-defaults-1" id="toc-entry-90">Writer Specific Defaults</a></li>
<li><a class="reference internal" href="#embed-images" id="toc-entry-91">embed_images</a></li>
<li><a class="reference internal" href="#image-loading" id="toc-entry-92">image_loading</a></li>
<li><a class="reference internal" href="#section-self-link" id="toc-entry-93">section_self_link</a></li>
</ul>
</li>
<li><a class="reference internal" href="#pep-html-writer" id="toc-entry-94">[pep_html writer]</a><ul>
<li><a class="reference internal" href="#writer-specific-defaults-2" id="toc-entry-95">Writer Specific Defaults</a></li>
<li><a class="reference internal" href="#no-random" id="toc-entry-96">no_random</a></li>
<li><a class="reference internal" href="#pep-home" id="toc-entry-97">pep_home</a></li>
<li><a class="reference internal" href="#python-home" id="toc-entry-98">python_home</a></li>
</ul>
</li>
<li><a class="reference internal" href="#s5-html-writer" id="toc-entry-99">[s5_html writer]</a><ul>
<li><a class="reference internal" href="#writer-specific-defaults-3" id="toc-entry-100">Writer Specific Defaults</a></li>
<li><a class="reference internal" href="#hidden-controls" id="toc-entry-101">hidden_controls</a></li>
<li><a class="reference internal" href="#current-slide" id="toc-entry-102">current_slide</a></li>
<li><a class="reference internal" href="#overwrite-theme-files" id="toc-entry-103">overwrite_theme_files</a></li>
<li><a class="reference internal" href="#theme" id="toc-entry-104">theme</a></li>
<li><a class="reference internal" href="#theme-url" id="toc-entry-105">theme_url</a></li>
<li><a class="reference internal" href="#view-mode" id="toc-entry-106">view_mode</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#latex-writers" id="toc-entry-107">[latex writers]</a><ul>
<li><a class="reference internal" href="#attribution-1" id="toc-entry-108">attribution</a></li>
<li><a class="reference internal" href="#compound-enumerators" id="toc-entry-109">compound_enumerators</a></li>
<li><a class="reference internal" href="#documentclass" id="toc-entry-110">documentclass</a></li>
<li><a class="reference internal" href="#documentoptions" id="toc-entry-111">documentoptions</a></li>
<li><a class="reference internal" href="#docutils-footnotes" id="toc-entry-112">docutils_footnotes</a></li>
<li><a class="reference internal" href="#embed-stylesheet-1" id="toc-entry-113">embed_stylesheet</a></li>
<li><a class="reference internal" href="#footnote-references-1" id="toc-entry-114">footnote_references</a></li>
<li><a class="reference internal" href="#graphicx-option" id="toc-entry-115">graphicx_option</a></li>
<li><a class="reference internal" href="#hyperlink-color" id="toc-entry-116">hyperlink_color</a></li>
<li><a class="reference internal" href="#hyperref-options" id="toc-entry-117">hyperref_options</a></li>
<li><a class="reference internal" href="#latex-preamble" id="toc-entry-118">latex_preamble</a></li>
<li><a class="reference internal" href="#legacy-class-functions" id="toc-entry-119">legacy_class_functions</a></li>
<li><a class="reference internal" href="#legacy-column-widths" id="toc-entry-120">legacy_column_widths</a></li>
<li><a class="reference internal" href="#literal-block-env" id="toc-entry-121">literal_block_env</a></li>
<li><a class="reference internal" href="#reference-label" id="toc-entry-122">reference_label</a></li>
<li><a class="reference internal" href="#section-enumerator-separator" id="toc-entry-123">section_enumerator_separator</a></li>
<li><a class="reference internal" href="#section-prefix-for-enumerators" id="toc-entry-124">section_prefix_for_enumerators</a></li>
<li><a class="reference internal" href="#stylesheet-1" id="toc-entry-125">stylesheet</a></li>
<li><a class="reference internal" href="#stylesheet-dirs-1" id="toc-entry-126">stylesheet_dirs</a></li>
<li><a class="reference internal" href="#stylesheet-path-2" id="toc-entry-127">stylesheet_path</a></li>
<li><a class="reference internal" href="#table-style-1" id="toc-entry-128">table_style</a></li>
<li><a class="reference internal" href="#template-1" id="toc-entry-129">template</a></li>
<li><a class="reference internal" href="#use-bibtex" id="toc-entry-130">use_bibtex</a></li>
<li><a class="reference internal" href="#use-latex-abstract" id="toc-entry-131">use_latex_abstract</a></li>
<li><a class="reference internal" href="#use-latex-citations" id="toc-entry-132">use_latex_citations</a></li>
<li><a class="reference internal" href="#use-latex-docinfo" id="toc-entry-133">use_latex_docinfo</a></li>
<li><a class="reference internal" href="#use-latex-toc" id="toc-entry-134">use_latex_toc</a></li>
<li><a class="reference internal" href="#use-part-section" id="toc-entry-135">use_part_section</a></li>
<li><a class="reference internal" href="#latex2e-writer" id="toc-entry-136">[latex2e writer]</a><ul>
<li><a class="reference internal" href="#writer-specific-defaults-4" id="toc-entry-137">Writer Specific Defaults</a></li>
<li><a class="reference internal" href="#font-encoding" id="toc-entry-138">font_encoding</a></li>
</ul>
</li>
<li><a class="reference internal" href="#xetex-writer" id="toc-entry-139">[xetex writer]</a><ul>
<li><a class="reference internal" href="#writer-specific-defaults-5" id="toc-entry-140">Writer Specific Defaults</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#odf-odt-writer" id="toc-entry-141">[odf_odt writer]</a><ul>
<li><a class="reference internal" href="#stylesheet-2" id="toc-entry-142">stylesheet</a></li>
<li><a class="reference internal" href="#odf-config-file" id="toc-entry-143">odf-config-file</a></li>
<li><a class="reference internal" href="#cloak-email-addresses-1" id="toc-entry-144">cloak-email-addresses</a></li>
<li><a class="reference internal" href="#no-cloak-email-addresses" id="toc-entry-145">no-cloak-email-addresses</a></li>
<li><a class="reference internal" href="#table-border-thickness" id="toc-entry-146">table-border-thickness</a></li>
<li><a class="reference internal" href="#add-syntax-highlighting" id="toc-entry-147">add-syntax-highlighting</a></li>
<li><a class="reference internal" href="#no-syntax-highlighting" id="toc-entry-148">no-syntax-highlighting</a></li>
<li><a class="reference internal" href="#create-sections" id="toc-entry-149">create-sections</a></li>
<li><a class="reference internal" href="#no-sections" id="toc-entry-150">no-sections</a></li>
<li><a class="reference internal" href="#create-links" id="toc-entry-151">create-links</a></li>
<li><a class="reference internal" href="#no-links" id="toc-entry-152">no-links</a></li>
<li><a class="reference internal" href="#endnotes-end-doc" id="toc-entry-153">endnotes-end-doc</a></li>
<li><a class="reference internal" href="#no-endnotes-end-doc" id="toc-entry-154">no-endnotes-end-doc</a></li>
<li><a class="reference internal" href="#generate-list-toc" id="toc-entry-155">generate-list-toc</a></li>
<li><a class="reference internal" href="#generate-oowriter-toc" id="toc-entry-156">generate-oowriter-toc</a></li>
<li><a class="reference internal" href="#custom-odt-header" id="toc-entry-157">custom-odt-header</a></li>
<li><a class="reference internal" href="#custom-odt-footer" id="toc-entry-158">custom-odt-footer</a></li>
</ul>
</li>
<li><a class="reference internal" href="#pseudoxml-writer" id="toc-entry-159">[pseudoxml writer]</a><ul>
<li><a class="reference internal" href="#detailed" id="toc-entry-160">detailed</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#applications" id="toc-entry-161">[applications]</a><ul>
<li><a class="reference internal" href="#buildhtml-application" id="toc-entry-162">[buildhtml application]</a><ul>
<li><a class="reference internal" href="#dry-run" id="toc-entry-163">dry_run</a></li>
<li><a class="reference internal" href="#ignore" id="toc-entry-164">ignore</a></li>
<li><a class="reference internal" href="#prune" id="toc-entry-165">prune</a></li>
<li><a class="reference internal" href="#recurse" id="toc-entry-166">recurse</a></li>
<li><a class="reference internal" href="#silent" id="toc-entry-167">silent</a></li>
<li><a class="reference internal" href="#writer" id="toc-entry-168">writer</a></li>
</ul>
</li>
<li><a class="reference internal" href="#docutils-application-1" id="toc-entry-169">[docutils application]</a><ul>
<li><a class="reference internal" href="#reader" id="toc-entry-170">reader</a></li>
<li><a class="reference internal" href="#parser" id="toc-entry-171">parser</a></li>
<li><a class="reference internal" href="#writer-1" id="toc-entry-172">writer</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#other-settings" id="toc-entry-173">Other Settings</a><ul>
<li><a class="reference internal" href="#command-line-only" id="toc-entry-174">Command-Line Only</a><ul>
<li><a class="reference internal" href="#config" id="toc-entry-175">config</a></li>
</ul>
</li>
<li><a class="reference internal" href="#internal-settings" id="toc-entry-176">Internal Settings</a><ul>
<li><a class="reference internal" href="#config-files" id="toc-entry-177">_config_files</a></li>
<li><a class="reference internal" href="#directories" id="toc-entry-178">_directories</a></li>
<li><a class="reference internal" href="#disable-config" id="toc-entry-179">_disable_config</a></li>
<li><a class="reference internal" href="#destination" id="toc-entry-180">_destination</a></li>
<li><a class="reference internal" href="#source" id="toc-entry-181">_source</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#old-format-configuration-files" id="toc-entry-182">Old-Format Configuration Files</a></li>
</ul>
</div>
<div class="section" id="configuration-files">
<h1><a class="toc-backref" href="#toc-entry-1">Configuration Files</a></h1>
<p>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 <a class="reference external" href="tools.html">front-end tool</a>.
Configuration file settings override the built-in defaults, and
command-line options override all.
For the technicalities, see <a class="reference external" href="../api/runtime-settings.html">Docutils Runtime Settings</a>.</p>
<p>By default, Docutils checks the following places for configuration
files, in the following order:</p>
<ol class="arabic simple">
<li><tt class="docutils literal">/etc/docutils.conf</tt>: This is a system-wide configuration file,
applicable to all Docutils processing on the system.</li>
<li><tt class="docutils literal">./docutils.conf</tt>: 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.</li>
<li><tt class="docutils literal"><span class="pre">~/.docutils</span></tt>: 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.</li>
</ol>
<p>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.</p>
<p>The default implicit config file paths can be overridden by the
<tt class="docutils literal">DOCUTILSCONFIG</tt> environment variable. <tt class="docutils literal">DOCUTILSCONFIG</tt> 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.</p>
<p>In addition, a configuration file may be explicitly specified with the
<tt class="docutils literal"><span class="pre">--config</span></tt> command-line option. This configuration file is read after
the three implicit ones listed above (or the ones defined by the
<tt class="docutils literal">DOCUTILSCONFIG</tt> environment variable), and its entries will have
priority.</p>
</div>
<div class="section" id="configuration-file-syntax">
<h1><a class="toc-backref" href="#toc-entry-2">Configuration File Syntax</a></h1>
<p>Configuration files are UTF-8-encoded text files. The
<a class="reference external" href="https://docs.python.org/3/library/configparser.html">ConfigParser.py</a> module from <a class="reference external" href="https://www.python.org/">Python</a>'s standard library is used to
read them. From its documentation:</p>
<blockquote>
The configuration file consists of sections, lead by a "[section]"
header and followed by "name: value" entries, with continuations
in the style of <a class="reference external" href="https://www.rfc-editor.org/rfc/rfc822.txt">RFC 822</a>; "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.</blockquote>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">No format string interpolation is done.</p>
</div>
<p>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.</p>
<p>For on/off switch settings (<span class="target" id="booleans">booleans</span>), the following values are
recognized:</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">On:</th><td class="field-body">"true", "yes", "on", "1"</td>
</tr>
<tr class="field"><th class="field-name">Off:</th><td class="field-body">"false", "no", "off", "0", "" (no value)</td>
</tr>
</tbody>
</table>
<p id="list">List values can be comma- or colon-delimited.</p>
<p><a class="reference internal" href="#strip-classes">strip_classes</a>, <a class="reference internal" href="#strip-elements-with-classes">strip_elements_with_classes</a>, stylesheet, and
stylesheet_path use the comma as delimiter,
whitespace around list values is stripped.</p>
<pre class="literal-block">
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
</pre>
<p><a class="reference internal" href="#expose-internals">expose_internals</a>, <a class="reference internal" href="#ignore">ignore</a> and <a class="reference internal" href="#prune">prune</a> use the colon as delimiter and do not
strip whitespace:</p>
<pre class="literal-block">
expose_internals: b:c:d
</pre>
<div class="section" id="example">
<h2><a class="toc-backref" href="#toc-entry-3">Example</a></h2>
<p>This is from the <tt class="docutils literal">tools/docutils.conf</tt> configuration file supplied
with Docutils:</p>
<pre class="literal-block">
# 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
</pre>
<p>Individual configuration sections and settings are described in the
following section.</p>
</div>
</div>
<div class="section" id="configuration-file-sections-entries">
<h1><a class="toc-backref" href="#toc-entry-4">Configuration File Sections & Entries</a></h1>
<p>Below are the Docutils runtime settings, listed by config file
section. <strong>Any setting may be specified in any section, but only
settings from active sections will be used.</strong> Sections correspond to
Docutils components (module name or alias; section names are always in
lowercase letters). Each <a class="reference external" href="tools.html">Docutils application</a> 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:</p>
<ol class="arabic simple">
<li><a class="reference internal" href="#general">[general]</a></li>
<li><a class="reference internal" href="#parsers">[parsers]</a>, parser dependencies, and the section specific to the
Parser used ("[... parser]").</li>
<li><a class="reference internal" href="#readers">[readers]</a>, reader dependencies, and the section specific to the
Reader used ("[... reader]"). For example, <a class="reference internal" href="#pep-reader">[pep reader]</a> depends
on <a class="reference internal" href="#standalone-reader">[standalone reader]</a>.</li>
<li><a class="reference internal" href="#writers">[writers]</a>, writer family ("[... writers]"; if applicable),
writer dependencies, and the section specific to the writer used
("[... writer]"). For example, <a class="reference internal" href="#pep-html-writer">[pep_html writer]</a> depends
on <a class="reference internal" href="#html-writers">[html writers]</a> and <a class="reference internal" href="#html4css1-writer">[html4css1 writer]</a>.</li>
<li><a class="reference internal" href="#applications">[applications]</a>, application dependencies, and the section
specific to the Application (front-end tool) in use
("[... application]").</li>
</ol>
<p>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.</p>
<p>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.</p>
<p>Some knowledge of <a class="reference external" href="https://www.python.org/">Python</a> is assumed for some attributes.</p>
<div class="section" id="general">
<h2><a class="toc-backref" href="#toc-entry-5">[general]</a></h2>
<p>Settings in the "[general]" section are always applied.</p>
<div class="section" id="auto-id-prefix">
<h3><a class="toc-backref" href="#toc-entry-6">auto_id_prefix</a></h3>
<p>Prefix prepended to all auto-generated <cite>identifier keys</cite> generated within
the document, after <a class="reference internal" href="#id-prefix">id_prefix</a>. Ensure the value conforms to the
restrictions on identifiers in the output format, as it is not subjected to
the <a class="reference external" href="../ref/rst/directives.html#identifier-normalization">identifier normalization</a>.</p>
<p>A trailing "%" is replaced with the tag name (new in Docutils 0.16).</p>
<p>Default: "%" (changed in 0.18 from "id").
Option: <tt class="docutils literal"><span class="pre">--auto-id-prefix</span></tt> (hidden, intended mainly for programmatic use).</p>
</div>
<div class="section" id="datestamp">
<h3><a class="toc-backref" href="#toc-entry-7">datestamp</a></h3>
<p>Include a time/datestamp in the document footer. Contains a
format string for Python's <a class="reference external" href="https://docs.python.org/3/library/time.html#time.strftime">time.strftime()</a>.</p>
<p>Default: None.
Options: <tt class="docutils literal"><span class="pre">--date,</span> <span class="pre">-d,</span> <span class="pre">--time,</span> <span class="pre">-t,</span> <span class="pre">--no-datestamp</span></tt>.</p>
<p>Configuration file entry examples:</p>
<pre class="literal-block">
# 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:
</pre>
</div>
<div class="section" id="debug">
<h3><a class="toc-backref" href="#toc-entry-8">debug</a></h3>
<p>Report debug-level system messages.</p>
<p>Default: don't (None). Options: <tt class="docutils literal"><span class="pre">--debug,</span> <span class="pre">--no-debug</span></tt>.</p>
</div>
<div class="section" id="dump-internals">
<h3><a class="toc-backref" href="#toc-entry-9">dump_internals</a></h3>
<p>At the end of processing, write all internal attributes of the
document (<tt class="docutils literal">document.__dict__</tt>) to stderr.</p>
<p>Default: don't (None).
Option: <tt class="docutils literal"><span class="pre">--dump-internals</span></tt> (hidden, for development use only).</p>
</div>
<div class="section" id="dump-pseudo-xml">
<h3><a class="toc-backref" href="#toc-entry-10">dump_pseudo_xml</a></h3>
<p>At the end of processing, write the pseudo-XML representation of
the document to stderr.</p>
<p>Default: don't (None).
Option: <tt class="docutils literal"><span class="pre">--dump-pseudo-xml</span></tt> (hidden, for development use only).</p>
</div>
<div class="section" id="dump-settings">
<h3><a class="toc-backref" href="#toc-entry-11">dump_settings</a></h3>
<p>At the end of processing, write all Docutils settings to stderr.</p>
<p>Default: don't (None).
Option: <tt class="docutils literal"><span class="pre">--dump-settings</span></tt> (hidden, for development use only).</p>
</div>
<div class="section" id="dump-transforms">
<h3><a class="toc-backref" href="#toc-entry-12">dump_transforms</a></h3>
<p>At the end of processing, write a list of all transforms applied
to the document to stderr.</p>
<p>Default: don't (None).
Option: <tt class="docutils literal"><span class="pre">--dump-transforms</span></tt> (hidden, for development use only).</p>
</div>
<div class="section" id="error-encoding">
<h3><a class="toc-backref" href="#toc-entry-13">error_encoding</a></h3>
<p>The text encoding for error output.</p>
<p>Default: "ascii". Options: <tt class="docutils literal"><span class="pre">--error-encoding,</span> <span class="pre">-e</span></tt>.</p>
</div>
<div class="section" id="error-encoding-error-handler">
<h3><a class="toc-backref" href="#toc-entry-14">error_encoding_error_handler</a></h3>
<p>The error handler for unencodable characters in error output.
Acceptable values are the <a class="reference external" href="https://docs.python.org/3/library/codecs.html#error-handlers">Error Handlers</a> of Python's "encoding" module.
See also <a class="reference internal" href="#output-encoding-error-handler">output_encoding_error_handler</a>.</p>
<p>Default: "backslashreplace"
Options: <tt class="docutils literal"><span class="pre">--error-encoding-error-handler,</span> <span class="pre">--error-encoding,</span> <span class="pre">-e</span></tt>.</p>
</div>
<div class="section" id="exit-status-level">
<h3><a class="toc-backref" href="#toc-entry-15">exit_status_level</a></h3>
<p>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.).</p>
<p>Default: disabled (5). Option: <tt class="docutils literal"><span class="pre">--exit-status</span></tt>.</p>
</div>
<div class="section" id="expose-internals">
<h3><a class="toc-backref" href="#toc-entry-16">expose_internals</a></h3>
<p><a class="reference internal" href="#list">List</a> 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.</p>
<p>Default: don't (None).
Option: <tt class="docutils literal"><span class="pre">--expose-internal-attribute</span></tt> (hidden, for development use only).</p>
</div>
<div class="section" id="footnote-backlinks">
<h3><a class="toc-backref" href="#toc-entry-17">footnote_backlinks</a></h3>
<p>Enable or disable backlinks from <a class="reference external" href="../ref/rst/restructuredtext.html#footnotes">footnotes</a> and <a class="reference external" href="../ref/rst/restructuredtext.html#citations">citations</a> to their
references.</p>
<p>Default: enabled (True).
Options: <tt class="docutils literal"><span class="pre">--footnote-backlinks,</span> <span class="pre">--no-footnote-backlinks</span></tt>.</p>
</div>
<div class="section" id="generator">
<h3><a class="toc-backref" href="#toc-entry-18">generator</a></h3>
<p>Include a "Generated by Docutils" credit and link in the document footer.</p>
<p>Default: off (None). Options: <tt class="docutils literal"><span class="pre">--generator,</span> <span class="pre">-g,</span> <span class="pre">--no-generator</span></tt>.</p>
</div>
<div class="section" id="halt-level">
<h3><a class="toc-backref" href="#toc-entry-19">halt_level</a></h3>
<p>The threshold at or above which system messages are converted to
exceptions, halting execution immediately. If <a class="reference internal" href="#traceback">traceback</a> is set, the
exception will propagate; otherwise, Docutils will exit.</p>
<p>See also <a class="reference internal" href="#report-level">report_level</a>.</p>
<p>Default: severe (4). Options: <tt class="docutils literal"><span class="pre">--halt,</span> <span class="pre">--strict</span></tt>.</p>
</div>
<div class="section" id="id-prefix">
<h3><a class="toc-backref" href="#toc-entry-20">id_prefix</a></h3>
<p>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 <a class="reference external" href="../ref/rst/directives.html#identifier-normalization">identifier normalization</a>.
See also <a class="reference internal" href="#auto-id-prefix">auto_id_prefix</a>.</p>
<p>Default: "" (empty).
Option: <tt class="docutils literal"><span class="pre">--id-prefix</span></tt> (hidden, intended mainly for programmatic use).</p>
</div>
<div class="section" id="input-encoding">
<h3><a class="toc-backref" href="#toc-entry-21">input_encoding</a></h3>
<p>The text encoding for input.</p>
<p>Default: auto-detect (None). Options: <tt class="docutils literal"><span class="pre">--input-encoding,</span> <span class="pre">-i</span></tt>.</p>
</div>
<div class="section" id="input-encoding-error-handler">
<h3><a class="toc-backref" href="#toc-entry-22">input_encoding_error_handler</a></h3>
<p>The error handler for undecodable characters in the input.
Acceptable values are the <a class="reference external" href="https://docs.python.org/3/library/codecs.html#error-handlers">Error Handlers</a> of Python's "encoding" module,
including:</p>
<dl class="docutils">
<dt>strict</dt>
<dd>Raise an exception in case of an encoding error.</dd>
<dt>replace</dt>
<dd>Replace malformed data with the official Unicode replacement
character, U+FFFD.</dd>
<dt>ignore</dt>
<dd>Ignore malformed data and continue without further notice.</dd>
</dl>
<p>Default: "strict".
Options: <tt class="docutils literal"><span class="pre">--input-encoding-error-handler,</span> <span class="pre">--input-encoding,</span> <span class="pre">-i</span></tt>.</p>
</div>
<div class="section" id="language-code">
<h3><a class="toc-backref" href="#toc-entry-23">language_code</a></h3>
<p>Case-insensitive <a class="reference external" href="https://www.w3.org/International/articles/language-tags/">language tag</a> as defined in <a class="reference external" href="https://www.rfc-editor.org/rfc/bcp/bcp47.txt">BCP 47</a>.</p>
<p>Sets the document language, also used for localized directive and
role names as well as Docutils-generated text.</p>
<p>A typical language identifier consists of a 2-letter language code
from <a class="reference external" href="http://www.loc.gov/standards/iso639-2/php/English_list.php">ISO 639</a> (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 <a class="reference external" href="http://www.iso.ch/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/index.html">ISO 3166</a>
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).</p>
<p>The language of document parts can be specified with a
"language-<language tag>" <a class="reference external" href="../ref/doctree.html#classes">class attribute</a>, e.g.
<tt class="docutils literal">.. class:: <span class="pre">language-el-polyton</span></tt> for a quote in polytonic Greek.</p>
<p>Default: English ("en"). Options: <tt class="docutils literal"><span class="pre">--language,</span> <span class="pre">-l</span></tt>.</p>
</div>
<div class="section" id="output-encoding">
<h3><a class="toc-backref" href="#toc-entry-24">output_encoding</a></h3>
<p>The text encoding for output.</p>
<p>Default: "utf-8". Options: <tt class="docutils literal"><span class="pre">--output-encoding,</span> <span class="pre">-o</span></tt>.</p>
</div>
<div class="section" id="output-encoding-error-handler">
<h3><a class="toc-backref" href="#toc-entry-25">output_encoding_error_handler</a></h3>
<p>The error handler for unencodable characters in the output.
Acceptable values are the <a class="reference external" href="https://docs.python.org/3/library/codecs.html#error-handlers">Error Handlers</a> of Python's "encoding" module,
including:</p>
<dl class="docutils">
<dt>strict</dt>
<dd>Raise an exception in case of an encoding error.</dd>
<dt>replace</dt>
<dd>Replace malformed data with a suitable replacement marker,
such as "?".</dd>
<dt>ignore</dt>
<dd>Ignore malformed data and continue without further notice.</dd>
<dt>xmlcharrefreplace</dt>
<dd>Replace with the appropriate XML character reference, such as
"<tt class="docutils literal">&#8224;</tt>".</dd>
<dt>backslashreplace</dt>
<dd>Replace with backslash escape sequences, such as "<tt class="docutils literal">\u2020</tt>".</dd>
</dl>
<p>Default: "strict".
Options: <tt class="docutils literal"><span class="pre">--output-encoding-error-handler,</span> <span class="pre">--output-encoding,</span> <span class="pre">-o</span></tt>.</p>
</div>
<div class="section" id="record-dependencies">
<h3><a class="toc-backref" href="#toc-entry-26">record_dependencies</a></h3>
<p>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 <a class="footnote-reference" href="#dependencies" id="footnote-reference-1">[1]</a>. <a class="footnote-reference" href="#pwd" id="footnote-reference-2">[4]</a> The format is one path per
line with forward slashes as separator, the encoding is UTF-8.</p>
<p>Set to <tt class="docutils literal">-</tt> in order to write dependencies to stdout.</p>
<p>This option is particularly useful in conjunction with programs like
<tt class="docutils literal">make</tt> using <tt class="docutils literal">Makefile</tt> rules like:</p>
<pre class="literal-block">
ham.html: ham.txt $(shell cat hamdeps.txt)
rst2html.py --record-dependencies=hamdeps.txt ham.txt ham.html
</pre>
<p>If the filesystem encoding differs from UTF-8, replace the <tt class="docutils literal">cat</tt>
command with a call to a converter, e.g.:</p>
<pre class="literal-block">
$(shell iconv -f utf-8 -t latin1 hamdeps.txt)
</pre>
<p>Default: None. Option: <tt class="docutils literal"><span class="pre">--record-dependencies</span></tt>.</p>
<table class="docutils footnote" frame="void" id="dependencies" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#footnote-reference-1">[1]</a></td><td>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.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="report-level">
<h3><a class="toc-backref" href="#toc-entry-27">report_level</a></h3>
<p>Report system messages at or higher than <level>:</p>
<p>1 info
2 warning
3 error
4 severe
5 none</p>
<p>See also <a class="reference internal" href="#halt-level">halt_level</a>.</p>
<p>Default: warning (2).
Options: <tt class="docutils literal"><span class="pre">--report,</span> <span class="pre">-r,</span> <span class="pre">--verbose,</span> <span class="pre">-v,</span> <span class="pre">--quiet,</span> <span class="pre">-q</span></tt>.</p>
</div>
<div class="section" id="sectnum-xform">
<h3><a class="toc-backref" href="#toc-entry-28">sectnum_xform</a></h3>
<p>Enable or disable automatic section numbering by Docutils
(docutils.transforms.parts.SectNum) associated with the <a class="reference external" href="../ref/rst/directives.html#sectnum">sectnum
directive</a>.</p>
<p>If disabled, section numbers might be added to the output by the
renderer (e.g. by LaTeX or via a CSS style definition).</p>
<p>Default: enabled (True).
Options: <tt class="docutils literal"><span class="pre">--section-numbering</span></tt>, <tt class="docutils literal"><span class="pre">--no-section-numbering</span></tt>.</p>
</div>
<div class="section" id="source-link">
<h3><a class="toc-backref" href="#toc-entry-29">source_link</a></h3>
<p>Include a "View document source" link in the document footer. URL will
be relative to the destination.</p>
<p>Default: don't (None).
Options: <tt class="docutils literal"><span class="pre">--source-link,</span> <span class="pre">-s,</span> <span class="pre">--no-source-link</span></tt>.</p>
</div>
<div class="section" id="source-url">
<h3><a class="toc-backref" href="#toc-entry-30">source_url</a></h3>
<p>An explicit URL for a "View document source" link, used verbatim.</p>
<p>Default: compute if source_link (None).
Options: <tt class="docutils literal"><span class="pre">--source-url,</span> <span class="pre">--no-source-link</span></tt>.</p>
</div>
<div class="section" id="strict-visitor">
<h3><a class="toc-backref" href="#toc-entry-31">strict_visitor</a></h3>
<p>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.</p>
<p>Default: disabled (None).
Option: <tt class="docutils literal"><span class="pre">--strict-visitor</span></tt> (hidden, for development use only).</p>
</div>
<div class="section" id="strip-classes">
<h3><a class="toc-backref" href="#toc-entry-32">strip_classes</a></h3>
<p>Comma-separated <a class="reference internal" href="#list">list</a> of "classes" attribute values to remove from all
elements in the document tree. The command line option may be used more
than once.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Potentially dangerous; use with caution.</p>
</div>
<p>Default: disabled (None). Option: <tt class="docutils literal"><span class="pre">--strip-class</span></tt>.</p>
</div>
<div class="section" id="strip-comments">
<h3><a class="toc-backref" href="#toc-entry-33">strip_comments</a></h3>
<p>Enable the removal of comment elements from the document tree.</p>
<p>Default: disabled (None).
Options: <tt class="docutils literal"><span class="pre">--strip-comments</span></tt>, <tt class="docutils literal"><span class="pre">--leave-comments</span></tt>.</p>
</div>
<div class="section" id="strip-elements-with-classes">
<h3><a class="toc-backref" href="#toc-entry-34">strip_elements_with_classes</a></h3>
<p>Comma-separated <a class="reference internal" href="#list">list</a> of "classes" attribute values;
matching elements are removed from the document tree.
The command line option may be used more than once.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Potentially dangerous; use with caution.</p>
</div>
<p>Default: disabled (None). Option: <tt class="docutils literal"><span class="pre">--strip-element-with-class</span></tt>.</p>
</div>
<div class="section" id="title">
<h3><a class="toc-backref" href="#toc-entry-35">title</a></h3>
<p>The <cite>document title</cite> as metadata which does not become part of the
document body. Stored as the document's <a class="reference external" href="../ref/doctree.html#title-attribute">title attribute</a>.
For example, in HTML output the metadata document title
appears in the title bar of the browser window.</p>
<p>This setting overrides a displayed <a class="reference external" href="../ref/rst/restructuredtext.html#document-title">document title</a> and
is overridden by a <a class="reference external" href="../ref/rst/directives.html#metadata-document-title">"title" directive</a>.</p>
<p>Default: none. Option: <tt class="docutils literal"><span class="pre">--title</span></tt>.</p>
</div>
<div class="section" id="toc-backlinks">
<h3><a class="toc-backref" href="#toc-entry-36">toc_backlinks</a></h3>
<p>Enable backlinks from section titles to table of contents entries
("entry"), to the top of the TOC ("top"), or disable ("none").</p>
<p>Default: "entry".
Options: <tt class="docutils literal"><span class="pre">--toc-entry-backlinks,</span> <span class="pre">--toc-top-backlinks,</span> <span class="pre">--no-toc-backlinks</span></tt>.</p>
</div>
<div class="section" id="traceback">
<h3><a class="toc-backref" href="#toc-entry-37">traceback</a></h3>
<p>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.</p>
<p>Default: disabled (None) unless Docutils is run programmatically
using the <a class="reference external" href="../api/publisher.html">Publisher Interface</a>.
Options: <tt class="docutils literal"><span class="pre">--traceback,</span> <span class="pre">--no-traceback</span></tt>.</p>
</div>
<div class="section" id="warning-stream">
<h3><a class="toc-backref" href="#toc-entry-38">warning_stream</a></h3>
<p>Path to a file for the output of system messages (warnings). <a class="footnote-reference" href="#pwd" id="footnote-reference-3">[4]</a></p>
<p>Default: stderr (None). Option: <tt class="docutils literal"><span class="pre">--warnings</span></tt>.</p>
</div>
</div>
<div class="section" id="parsers">
<h2><a class="toc-backref" href="#toc-entry-39">[parsers]</a></h2>
<p>Generic parser options:</p>
<div class="section" id="file-insertion-enabled">
<h3><a class="toc-backref" href="#toc-entry-40">file_insertion_enabled</a></h3>
<p>Enable or disable directives or directive that insert the contents of
external files, such as "<a class="reference external" href="../ref/rst/directives.html#include">include</a>" or "<a class="reference external" href="../ref/rst/directives.html#raw">raw</a>" with option "url".
A "warning" system message (including the directive text) is inserted
instead. (See also <a class="reference internal" href="#raw-enabled">raw_enabled</a> for another security-relevant setting.)</p>
<p>Default: enabled (True).
Options: <tt class="docutils literal"><span class="pre">--file-insertion-enabled,</span> <span class="pre">--no-file-insertion</span></tt>.</p>
</div>
<div class="section" id="line-length-limit">
<h3><a class="toc-backref" href="#toc-entry-41">line_length_limit</a></h3>
<p>Maximal number of characters in an input line or <a class="reference external" href="../ref/rst/directives.html#substitution">substitution</a>
definition. To prevent extraordinary high processing times or memory
usage for certain input constructs, a "warning" system message is
inserted instead.</p>
<p>Default: 10 000.
Option: <tt class="docutils literal"><span class="pre">--line-length-limit</span></tt></p>
<p>New in Docutils 0.17.</p>
</div>
<div class="section" id="raw-enabled">
<h3><a class="toc-backref" href="#toc-entry-42">raw_enabled</a></h3>
<p>Enable or disable the "<a class="reference external" href="../ref/rst/directives.html#raw">raw</a>" directive. A "warning" system message
(including the directive text) is inserted instead. See also
<a class="reference internal" href="#file-insertion-enabled">file_insertion_enabled</a> for another security-relevant setting.</p>
<p>Default: enabled (True). Options: <tt class="docutils literal"><span class="pre">--raw-enabled,</span> <span class="pre">--no-raw</span></tt>.</p>
</div>
<div class="section" id="restructuredtext-parser">
<h3><a class="toc-backref" href="#toc-entry-43">[restructuredtext parser]</a></h3>
<div class="section" id="character-level-inline-markup">
<h4><a class="toc-backref" href="#toc-entry-44">character_level_inline_markup</a></h4>
<p>Relax the <a class="reference external" href="../ref/rst/restructuredtext.html#inline-markup-recognition-rules">inline markup recognition rules</a>
requiring whitespace or punctuation around inline markup.</p>
<p>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).</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p>Potentially dangerous; use with caution.</p>
<p>When changing this setting to "True", inline markup characters in
URLs, names and formulas must be escaped to prevent recognition and
possible errors. Examples:</p>
<pre class="last literal-block">
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)
</pre>
</div>
<p>Default: disabled (False).
Options: <tt class="docutils literal"><span class="pre">--character-level-inline-markup,</span> <span class="pre">--word-level-inline-markup</span></tt>.</p>
<p>New in Docutils 0.13.</p>
</div>
<div class="section" id="pep-references">
<h4><a class="toc-backref" href="#toc-entry-45">pep_references</a></h4>
<p>Recognize and link to standalone PEP references (like "PEP 258").</p>
<p>Default: disabled (None); enabled (True) in PEP Reader.
Option: <tt class="docutils literal"><span class="pre">--pep-references</span></tt>.</p>
</div>
<div class="section" id="pep-base-url">
<h4><a class="toc-backref" href="#toc-entry-46">pep_base_url</a></h4>
<p>Base URL for PEP references.</p>
<p>Default: "<a class="reference external" href="https://peps.python.org/">https://peps.python.org/</a>".
Option: <tt class="docutils literal"><span class="pre">--pep-base-url</span></tt>.</p>
</div>
<div class="section" id="pep-file-url-template">
<h4><a class="toc-backref" href="#toc-entry-47">pep_file_url_template</a></h4>
<p>Template for PEP file part of URL, interpolated with the PEP
number and appended to <a class="reference internal" href="#pep-base-url">pep_base_url</a>.</p>
<p>Default: "pep-%04d". Option: <tt class="docutils literal"><span class="pre">--pep-file-url</span></tt>.</p>
</div>
<div class="section" id="rfc-references">
<h4><a class="toc-backref" href="#toc-entry-48">rfc_references</a></h4>
<p>Recognize and link to standalone RFC references (like "RFC 822").</p>
<p>Default: disabled (None); enabled (True) in PEP Reader.
Option: <tt class="docutils literal"><span class="pre">--rfc-references</span></tt>.</p>
</div>
<div class="section" id="rfc-base-url">
<h4><a class="toc-backref" href="#toc-entry-49">rfc_base_url</a></h4>
<p>Base URL for RFC references.</p>
<p>Default: "<a class="reference external" href="http://www.faqs.org/rfcs/">http://www.faqs.org/rfcs/</a>". Option: <tt class="docutils literal"><span class="pre">--rfc-base-url</span></tt>.</p>
</div>
<div class="section" id="smart-quotes">
<h4><a class="toc-backref" href="#toc-entry-50">smart_quotes</a></h4>
<p>Activate the <a class="reference external" href="smartquotes.html">SmartQuotes</a> transform to
change straight quotation marks to typographic form. <a class="reference external" href="https://en.wikipedia.org/wiki/Non-English_usage_of_quotation_marks">Quote characters</a>
are selected according to the language of the current block element (see
<a class="reference internal" href="#language-code">language_code</a>, <a class="reference internal" href="#smartquotes-locales">smartquotes_locales</a>, and the <a class="reference external" href="smartquotes.html#localization">pre-defined quote sets</a>).</p>
<p>Also changes consecutive runs of hyphen-minus and full stops (<tt class="docutils literal"><span class="pre">---</span></tt>,
<tt class="docutils literal"><span class="pre">--</span></tt>, <tt class="docutils literal">...</tt>) to em-dash, en-dash, and ellipsis Unicode characters
respectively.</p>
<p>Supported values:</p>
<dl class="docutils">
<dt><a class="reference internal" href="#booleans">booleans</a> (yes/no)</dt>
<dd>Use smart quotes?</dd>
<dt>alt (or "alternative")</dt>
<dd>Use alternative quote set (if defined for the language).</dd>
</dl>
<p>Default: "no". Option: <tt class="docutils literal"><span class="pre">--smart-quotes</span></tt>.</p>
<p>New in Docutils 0.10.</p>
</div>
<div class="section" id="smartquotes-locales">
<h4><a class="toc-backref" href="#toc-entry-51">smartquotes_locales</a></h4>
<p>Typographical quotes used by the <a class="reference external" href="smartquotes.html">SmartQuotes</a> transform.</p>
<p>A comma-separated <a class="reference internal" href="#list">list</a> 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.)</p>
<dl class="docutils">
<dt>Example:</dt>
<dd><p class="first">Ensure a correct leading apostrophe in <tt class="docutils literal">'s Gravenhage</tt> in Dutch (at the
cost of incorrect opening single quotes) and set French quotes to double
and single guillemets with inner padding:</p>
<pre class="last literal-block">
smartquote-locales: nl: „”’’,
fr: « : »:‹ : ›
</pre>
</dd>
</dl>
<p>Default: None. Option: <tt class="docutils literal"><span class="pre">--smartquotes-locales</span></tt>.</p>
<p>New in Docutils 0.14.</p>
</div>
<div class="section" id="syntax-highlight">
<h4><a class="toc-backref" href="#toc-entry-52">syntax_highlight</a></h4>
<p>Token type names used by <a class="reference external" href="https://pygments.org/">Pygments</a> when parsing contents of the <a class="reference external" href="../ref/rst/directives.html#code">code</a>
directive and role.</p>
<p>Supported values:</p>
<dl class="docutils">
<dt>long</dt>
<dd>Use hierarchy of long token type names.</dd>
<dt>short</dt>
<dd>Use short token type names. (For use with
<a class="reference external" href="https://pygments.org/docs/cmdline/#generating-styles">Pygments-generated stylesheets</a>.)</dd>
<dt>none</dt>
<dd>No code parsing. Use this to avoid the "Pygments not
found" warning when Pygments is not installed.</dd>
</dl>
<p>Default: "long". Option: <tt class="docutils literal"><span class="pre">--syntax-highlight</span></tt>.</p>
<p>New in Docutils 0.9.</p>
</div>
<div class="section" id="tab-width">
<h4><a class="toc-backref" href="#toc-entry-53">tab_width</a></h4>
<p>Number of spaces for hard tab expansion.</p>
<p>Default: 8. Option: <tt class="docutils literal"><span class="pre">--tab-width</span></tt>.</p>
</div>
<div class="section" id="trim-footnote-reference-space">
<h4><a class="toc-backref" href="#toc-entry-54">trim_footnote_reference_space</a></h4>
<p>Remove spaces before <a class="reference external" href="../ref/rst/restructuredtext.html#footnote-references">footnote references</a>?</p>
<p>Default: None <a class="footnote-reference" href="#footnote-1" id="footnote-reference-4">[2]</a></p>
<p>Options: <tt class="docutils literal"><span class="pre">--trim-footnote-reference-space,</span> <span class="pre">--leave-footnote-reference-space</span></tt>.</p>
<table class="docutils footnote" frame="void" id="footnote-1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#footnote-reference-4">[2]</a></td><td>Depending on the writer-specific <a class="reference internal" href="#footnote-references-setting">footnote_references setting</a>.
The footnote space is trimmed if the reference style is "superscript",
and it is left if the reference style is "brackets".</td></tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="myst-parser">
<span id="myst"></span><h3><a class="toc-backref" href="#toc-entry-55">[myst parser]</a></h3>
<p>Provided by the 3rd party package <a class="reference external" href="https://pypi.org/project/myst-docutils/">myst-docutils</a>.
See <a class="reference external" href="https://myst-parser.readthedocs.io/en/latest/docutils.html">MyST with Docutils</a> and its <a class="reference external" href="https://myst-parser.readthedocs.io/en/latest/sphinx/reference.html#sphinx-config-options">Sphinx configuration options</a>
(some settings are not available with Docutils).</p>
</div>
<div class="section" id="pycmark-parser">
<span id="pycmark"></span><h3><a class="toc-backref" href="#toc-entry-56">[pycmark parser]</a></h3>
<p>Provided by the 3rd party package <a class="reference external" href="https://pypi.org/project/pycmark/">pycmark</a>.
Currently no configuration settings.</p>
</div>
<div class="section" id="recommonmark-parser">
<span id="recommonmark"></span><h3><a class="toc-backref" href="#toc-entry-57">[recommonmark parser]</a></h3>
<p>Provisional, depends on (deprecated) 3rd-party package <a class="reference external" href="https://pypi.org/project/recommonmark/">recommonmark</a>.
Currently no configuration settings.</p>
</div>
</div>
<div class="section" id="readers">
<h2><a class="toc-backref" href="#toc-entry-58">[readers]</a></h2>
<div class="section" id="standalone-reader">
<h3><a class="toc-backref" href="#toc-entry-59">[standalone reader]</a></h3>
<div class="section" id="docinfo-xform">
<h4><a class="toc-backref" href="#toc-entry-60">docinfo_xform</a></h4>
<p>Enable or disable the <a class="reference external" href="../ref/rst/restructuredtext.html#bibliographic-fields">bibliographic field list</a> transform
(docutils.transforms.frontmatter.DocInfo).</p>
<p>Default: enabled (True). Options: <tt class="docutils literal"><span class="pre">--no-doc-info</span></tt>.</p>
</div>
<div class="section" id="doctitle-xform">
<h4><a class="toc-backref" href="#toc-entry-61">doctitle_xform</a></h4>
<p>Enable or disable the promotion of a lone top-level section title
to <a class="reference external" href="../ref/rst/restructuredtext.html#document-title">document title</a> (and subsequent section title to document
subtitle promotion; docutils.transforms.frontmatter.DocTitle).</p>
<p>Default: enabled (True). Options: <tt class="docutils literal"><span class="pre">--no-doc-title</span></tt>.</p>
</div>
<div class="section" id="sectsubtitle-xform">
<h4><a class="toc-backref" href="#toc-entry-62">sectsubtitle_xform</a></h4>
<p>Enable or disable the promotion of the title of a lone subsection
to a subtitle (docutils.transforms.frontmatter.SectSubTitle).</p>
<p>Default: disabled (False).
Options: <tt class="docutils literal"><span class="pre">--section-subtitles,</span> <span class="pre">--no-section-subtitles</span></tt>.</p>
</div>
</div>
<div class="section" id="pep-reader">
<h3><a class="toc-backref" href="#toc-entry-63">[pep reader]</a></h3>
<p>The <a class="reference internal" href="#pep-references">pep_references</a> and <a class="reference internal" href="#rfc-references">rfc_references</a> settings
(<a class="reference internal" href="#restructuredtext-parser">[restructuredtext parser]</a>) are set on by default.</p>
<!-- [python reader]
- - - - - - - - - - - - - - -
Not implemented. -->
</div>
</div>
<div class="section" id="writers">
<h2><a class="toc-backref" href="#toc-entry-64">[writers]</a></h2>
<div class="section" id="docutils-xml-writer">
<h3><a class="toc-backref" href="#toc-entry-65">[docutils_xml writer]</a></h3>
<div class="admonition caution">
<p class="first admonition-title">Caution!</p>
<ul class="last simple">
<li>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.</li>
</ul>
</div>
<div class="section" id="doctype-declaration">
<h4><a class="toc-backref" href="#toc-entry-66">doctype_declaration</a></h4>
<p>Generate XML with a DOCTYPE declaration.</p>
<p>Default: do (True). Options: <tt class="docutils literal"><span class="pre">--no-doctype</span></tt>.</p>
</div>
<div class="section" id="indents">
<h4><a class="toc-backref" href="#toc-entry-67">indents</a></h4>
<p>Generate XML with indents and newlines.</p>
<p>Default: don't (None). Options: <tt class="docutils literal"><span class="pre">--indents</span></tt>.</p>
</div>
<div class="section" id="newlines">
<h4><a class="toc-backref" href="#toc-entry-68">newlines</a></h4>
<p>Generate XML with newlines before and after tags.</p>
<p>Default: don't (None). Options: <tt class="docutils literal"><span class="pre">--newlines</span></tt>.</p>
</div>
<div class="section" id="xml-declaration">
<span id="xml-declaration-docutils-xml-writer"></span><h4><a class="toc-backref" href="#toc-entry-69">xml_declaration</a></h4>
<p>Generate XML with an XML declaration.
See also <a class="reference internal" href="#xml-declaration-html-writers">xml_declaration [html writers]</a>.</p>
<p>Default: do (True). Option: <tt class="docutils literal"><span class="pre">--no-xml-declaration</span></tt>.</p>
</div>
</div>
<div class="section" id="html-writers">
<h3><a class="toc-backref" href="#toc-entry-70">[html writers]</a></h3>
<div class="section" id="attribution">
<span id="attribution-html-writers"></span><h4><a class="toc-backref" href="#toc-entry-71">attribution</a></h4>
<p>Format for <a class="reference external" href="../ref/rst/restructuredtext.html#block-quotes">block quote</a> attributions: one of "dash" (em-dash
prefix), "parentheses"/"parens", or "none".
See also <a class="reference internal" href="#attribution-latex-writers">attribution [latex writers]</a>.</p>
<p>Default: "dash". Option: <tt class="docutils literal"><span class="pre">--attribution</span></tt>.</p>
</div>
<div class="section" id="cloak-email-addresses">
<h4><a class="toc-backref" href="#toc-entry-72">cloak_email_addresses</a></h4>
<p>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 <tt class="docutils literal"><span></tt> tags.
Furthermore, HTML entities are used to encode these characters in
order to further complicate decoding the email address. For
example, "<a class="reference external" href="mailto:abc@example.org">abc@example.org</a>" will be output as:</p>
<pre class="literal-block">
<a class="reference" href="mailto:abc&#37;&#52;&#48;example&#46;org">
abc<span>&#64;</span>example<span>&#46;</span>org</a>
</pre>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">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 <tt class="docutils literal">links</tt> browser) may decode
cloaked email addresses incorrectly.</p>
</div>
<p>Default: don't cloak (None). Option: <tt class="docutils literal"><span class="pre">--cloak-email-addresses</span></tt>.</p>
</div>
<div class="section" id="compact-lists">
<h4><a class="toc-backref" href="#toc-entry-73">compact_lists</a></h4>
<p>Remove extra vertical whitespace between items of <a class="reference external" href="../ref/rst/restructuredtext.html#bullet-lists">bullet lists</a> and
<a class="reference external" href="../ref/rst/restructuredtext.html#enumerated-lists">enumerated lists</a>, 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.</p>
<p>Default: enabled (True).
Options: <tt class="docutils literal"><span class="pre">--compact-lists,</span> <span class="pre">--no-compact-lists</span></tt>.</p>
</div>
<div class="section" id="compact-field-lists">
<h4><a class="toc-backref" href="#toc-entry-74">compact_field_lists</a></h4>
<p>Remove extra vertical whitespace between items of <a class="reference external" href="../ref/rst/restructuredtext.html#field-lists">field lists</a> 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.</p>
<p>Default: enabled (True).
Options: <tt class="docutils literal"><span class="pre">--compact-field-lists,</span> <span class="pre">--no-compact-field-lists</span></tt>.</p>
</div>
<div class="section" id="embed-stylesheet">
<span id="embed-stylesheet-html-writers"></span><h4><a class="toc-backref" href="#toc-entry-75">embed_stylesheet</a></h4>
<p>Embed the stylesheet in the output HTML file. The stylesheet file
must specified by the <a class="reference internal" href="#stylesheet-path">stylesheet_path</a> setting and must be
accessible during processing.
See also <a class="reference internal" href="#embed-stylesheet-latex-writers">embed_stylesheet [latex writers]</a>.</p>
<p>Default: enabled.
Options: <tt class="docutils literal"><span class="pre">--embed-stylesheet,</span> <span class="pre">--link-stylesheet</span></tt>.</p>
</div>
<div class="section" id="footnote-references">
<span id="footnote-references-html-writers"></span><span id="footnote-references-setting"></span><h4><a class="toc-backref" href="#toc-entry-76">footnote_references</a></h4>
<p>Format for <a class="reference external" href="../ref/rst/restructuredtext.html#footnote-references">footnote references</a>, one of "superscript" or "brackets".
See also <a class="reference internal" href="#footnote-references-latex-writers">footnote_references [latex writers]</a>.</p>
<p>Overrides <a class="footnote-reference" href="#override" id="footnote-reference-5">[5]</a> <a class="reference internal" href="#trim-footnote-reference-space">trim_footnote_reference_space</a>,
if the parser supports this option.</p>
<p>Default: "brackets". Option: <tt class="docutils literal"><span class="pre">--footnote-references</span></tt>.</p>
</div>
<div class="section" id="initial-header-level">
<h4><a class="toc-backref" href="#toc-entry-77">initial_header_level</a></h4>
<p>The initial level for header elements. This does not affect the
document title & subtitle; see <a class="reference internal" href="#doctitle-xform">doctitle_xform</a>.</p>
<p>Default: writer dependent (see <a class="reference internal" href="#html4css1-writer">[html4css1 writer]</a>, <a class="reference internal" href="#html5-writer">[html5 writer]</a>,
<a class="reference internal" href="#pep-html-writer">[pep_html writer]</a>).
Option: <tt class="docutils literal"><span class="pre">--initial-header-level</span></tt>.</p>
</div>
<div class="section" id="math-output">
<h4><a class="toc-backref" href="#toc-entry-78">math_output</a></h4>
<p>The format of mathematical content (<a class="reference external" href="../ref/rst/directives.html#math">math directive</a> and role) in
the output document. Supported values are (case insensitive):</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">HTML:</th><td class="field-body"><p class="first">Format math in standard HTML enhanced by CSS rules.
Requires the <tt class="docutils literal">math.css</tt> stylesheet (in the system
<a class="reference internal" href="#stylesheet-dirs-html-writers">stylesheet directory</a>)</p>
<p>A <a class="reference internal" href="#stylesheet-path-html-writers">stylesheet_path</a>
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).</p>
</td>
</tr>
<tr class="field"><th class="field-name">MathJax:</th><td class="field-body"><p class="first">Format math for display with <a class="reference external" href="http://www.mathjax.org/">MathJax</a>, a JavaScript-based math rendering
engine.</p>
<dl class="docutils">
<dt>Pro:</dt>
<dd><p class="first">Works across multiple browsers and platforms.</p>
<p class="last">Large set of <a class="reference external" href="http://docs.mathjax.org/en/latest/input/tex/macros/index.html">supported LaTeX math commands and constructs</a></p>
</dd>
<dt>Con:</dt>
<dd><p class="first last">Rendering requires JavaScript and an Internet connection or local
MathJax installation.</p>
</dd>
</dl>
<p>A URL pointing to a MathJax library should be appended after whitespace.
A warning is given if this is missing.</p>
<ul>
<li><p class="first">It is recommended to <a class="reference external" href="https://www.mathjax.org/#installnow">install</a> the MathJax library on the same
server as the rest of the deployed site files.</p>
<p>Example: Install the library at the top level of the web
server’s hierarchy in the directory <tt class="docutils literal">MathJax</tt> and set:</p>
<pre class="literal-block">
math-output: mathjax /MathJax/MathJax.js
</pre>
</li>
<li><p class="first">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.</p>
<p>Downside: Downloads JavaScript code from a third-party site --- opens
the door to cross-site scripting attacks!</p>
<p>Example: MathJax <a class="reference external" href="https://www.mathjax.org/#gettingstarted">getting started</a> documentation uses:</p>
<pre class="literal-block">
math-output: mathjax
https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
</pre>
<p>See <a class="reference external" href="https://www.jsdelivr.com/">https://www.jsdelivr.com/</a> for details and terms of use.</p>
</li>
<li><p class="first">Use a local MathJax installation on the <em>client</em> machine, e.g.:</p>
<pre class="literal-block">
math-output: MathJax file:/usr/share/javascript/mathjax/MathJax.js
</pre>
<p>This is the fallback if no URL is specified.</p>
</li>
</ul>
</td>
</tr>
<tr class="field"><th class="field-name">MathML:</th><td class="field-body"><p class="first">Embed math content as presentational <a class="reference external" href="https://www.w3.org/TR/MathML/">MathML</a>.</p>
<dl class="docutils">
<dt>Pro:</dt>
<dd><p class="first">The W3C recommendation for math on the web.</p>
<p class="last">Self-contained documents (no JavaScript, no external downloads).</p>
</dd>
<dt>Con:</dt>
<dd><p class="first">Limited <a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/MathML#browser_compatibility">browser support</a>.</p>
<p>Docutil's latex2mathml converter supports only a
<a class="reference external" href="../ref/rst/mathematics.html">subset of LaTeX math syntax</a>.</p>
<p class="last">With the "html4css1" writer, the resulting HTML document does
not validate, as there is no DTD for <cite>MathML + XHTML Transitional</cite>.
However, MathML-enabled browsers will render it fine.</p>
</dd>
</dl>
<p>An external converter can be appended after whitespace, e.g.,
<tt class="docutils literal"><span class="pre">--math-output="MathML</span> latexml"</tt>:</p>
<dl class="docutils">
<dt><a class="reference external" href="http://gva.noekeon.org/blahtexml/">blahtexml</a></dt>
<dd><p class="first last">Fast conversion, support for many symbols and environments, but no
"align" (or other equation-aligning) environment. (C++)</p>
</dd>
<dt><a class="reference external" href="http://dlmf.nist.gov/LaTeXML/">LaTeXML</a></dt>
<dd><p class="first last">Comprehensive macro support but <em>very</em> slow. (Perl)</p>
</dd>
<dt><a class="reference external" href="http://hutchinson.belmont.ma.us/tth/mml/">TtM</a></dt>
<dd><p class="first last">No "matrix", "align" and "cases" environments. Support may be removed.</p>
</dd>
</dl>
</td>
</tr>
<tr class="field"><th class="field-name">LaTeX:</th><td class="field-body"><p class="first">Include literal LaTeX code.</p>
<p class="last">The failsafe fallback.</p>
</td>
</tr>
</tbody>
</table>
<p>Default: HTML math.css. Option: <tt class="docutils literal"><span class="pre">--math-output</span></tt>.</p>
<p>New in Docutils 0.8.</p>
</div>
<div class="section" id="stylesheet">
<span id="stylesheet-html-writers"></span><h4><a class="toc-backref" href="#toc-entry-79">stylesheet</a></h4>
<p>A comma-separated list of CSS stylesheet URLs, used verbatim.
See also <a class="reference internal" href="#stylesheet-latex-writers">stylesheet [latex writers]</a>.</p>
<p>Overrides also <a class="reference internal" href="#stylesheet-path">stylesheet_path</a>. <a class="footnote-reference" href="#override" id="footnote-reference-6">[5]</a></p>
<p>Default: None. Option: <tt class="docutils literal"><span class="pre">--stylesheet</span></tt>.</p>
</div>
<div class="section" id="stylesheet-dirs">
<span id="stylesheet-dirs-html-writers"></span><h4><a class="toc-backref" href="#toc-entry-80">stylesheet_dirs</a></h4>
<p>A comma-separated list of directories where stylesheets can be found.
Used by the <a class="reference internal" href="#stylesheet-path">stylesheet_path</a> setting when expanding relative path arguments.</p>
<p>Note: This setting defines a "search path" (similar to the PATH variable for
executables). However, the term "path" is already used in the
<a class="reference internal" href="#stylesheet-path">stylesheet_path</a> setting with the meaning of a file location.</p>
<p>Default: the working directory of the process at launch and the directory
with default stylesheet files (writer and installation specific).
Use the <tt class="docutils literal"><span class="pre">--help</span></tt> option to get the exact value.
Option: <tt class="docutils literal"><span class="pre">--stylesheet-dirs</span></tt>.</p>
</div>
<div class="section" id="stylesheet-path-1">
<span id="stylesheet-path-html-writers"></span><span id="stylesheet-path"></span><h4><a class="toc-backref" href="#toc-entry-81">stylesheet_path</a></h4>
<p>A comma-separated list of paths to CSS stylesheets. Relative paths are
expanded if a matching file is found in the <a class="reference internal" href="#embed-stylesheet-html-writers">stylesheet_dirs</a>.
If <a class="reference internal" href="#stylesheet-dirs-html-writers">embed_stylesheet</a> is False, paths are rewritten relative to the
output HTML file.
See also <a class="reference internal" href="#stylesheet-path-latex-writers">stylesheet_path [latex writers]</a>.</p>
<p>Also overrides "stylesheet". <a class="footnote-reference" href="#override" id="footnote-reference-7">[5]</a>
Pass an empty string (to either "stylesheet" or "stylesheet_path") to
deactivate stylesheet inclusion.</p>
<p>Default: writer dependent (see <a class="reference internal" href="#html4css1-writer">[html4css1 writer]</a>, <a class="reference internal" href="#html5-writer">[html5 writer]</a>,
<a class="reference internal" href="#pep-html-writer">[pep_html writer]</a>).
Option: <tt class="docutils literal"><span class="pre">--stylesheet-path</span></tt>.</p>
</div>
<div class="section" id="table-style">
<span id="table-style-html-writers"></span><h4><a class="toc-backref" href="#toc-entry-82">table_style</a></h4>
<p>Class value(s) added to all <a class="reference external" href="../ref/rst/restructuredtext.html#tables">tables</a>.
See also <a class="reference internal" href="#table-style-latex-writers">table_style [latex writers]</a>.</p>
<p>The default CSS sylesheets define:</p>
<blockquote>
<dl class="docutils">
<dt>borderless</dt>
<dd>No borders around the table.</dd>
<dt>align-left, align-center, align-right</dt>
<dd>Align the tables</dd>
</dl>
</blockquote>
<p>The HTML5 stylesheets also define:</p>
<blockquote>
<dl class="docutils">
<dt>booktabs</dt>
<dd>Only lines above and below the table and a thin line after the head.</dd>
<dt>captionbelow</dt>
<dd>Place the table caption below the table
(New in Docutils 0.17).</dd>
</dl>
</blockquote>
<p>In addition, the HTML writers support:</p>
<blockquote>
<dl class="docutils">
<dt>colwidths-auto</dt>
<dd>Delegate the determination of table column widths to the back-end
(leave out the <tt class="docutils literal"><colgroup></tt> column specification).
Overridden by the "widths" option of the <a class="reference external" href="../ref/rst/directives.html#table">table directive</a>.</dd>
<dt>colwidths-grid</dt>
<dd>Backwards compatibility setting. Write column widths
determined from the source to the HTML file.
Overridden by the "widths" option of the <a class="reference external" href="../ref/rst/directives.html#table">table directive</a>.</dd>
</dl>
</blockquote>
<p>Default: "". Option: <tt class="docutils literal"><span class="pre">--table-style</span></tt>.</p>
</div>
<div class="section" id="template">
<span id="template-html-writers"></span><h4><a class="toc-backref" href="#toc-entry-83">template</a></h4>
<p>Path to template file, which must be encoded in UTF-8. <a class="footnote-reference" href="#pwd" id="footnote-reference-8">[4]</a>
See also <a class="reference internal" href="#template-latex-writers">template [latex writers]</a>.</p>
<p>Default: "template.txt" in the writer's directory (installed automatically;
for the exact machine-specific path, use the <tt class="docutils literal"><span class="pre">--help</span></tt> option).
Option: <tt class="docutils literal"><span class="pre">--template</span></tt>.</p>
</div>
<div class="section" id="xml-declaration-1">
<span id="xml-declaration-html-writers"></span><h4><a class="toc-backref" href="#toc-entry-84">xml_declaration</a></h4>
<p>Prepend an XML declaration.
See also <a class="reference internal" href="#xml-declaration-docutils-xml-writer">xml_declaration [docutils_xml writer]</a>.</p>
<div class="admonition caution">
<p class="first admonition-title">Caution!</p>
<p class="last">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.</p>
</div>
<p>Default: writer dependent.
Options: <tt class="docutils literal"><span class="pre">--xml-declaration</span></tt>, <tt class="docutils literal"><span class="pre">--no-xml-declaration</span></tt>.</p>
</div>
<div class="section" id="html4css1-writer">
<h4><a class="toc-backref" href="#toc-entry-85">[html4css1 writer]</a></h4>
<p>The <a class="reference external" href="html.html#html4css1">HTML4/CSS1 Writer</a> generates output that conforms to the
<a class="reference external" href="https://www.w3.org/TR/xhtml1/">XHTML 1 Transitional</a> specification.
It shares all settings defined in the <a class="reference internal" href="#html-writers">[html writers]</a>
<a class="reference internal" href="#configuration-file-sections-entries">configuration section</a>.</p>
<div class="section" id="writer-specific-defaults">
<h5><a class="toc-backref" href="#toc-entry-86">Writer Specific Defaults</a></h5>
<dl class="docutils">
<dt><a class="reference internal" href="#initial-header-level">initial_header_level</a></dt>
<dd>1 (for "<h1>")</dd>
<dt><a class="reference internal" href="#stylesheet-path-html-writers">stylesheet_path</a>:</dt>
<dd>"html4css1.css"</dd>
<dt><a class="reference internal" href="#xml-declaration-html-writers">xml_declaration</a></dt>
<dd>enabled (True)</dd>
</dl>
</div>
<div class="section" id="field-name-limit">
<h5><a class="toc-backref" href="#toc-entry-87">field_name_limit</a></h5>
<p>The maximum width (in characters) for one-column <a class="reference external" href="../ref/rst/restructuredtext.html#field-names">field names</a>. Longer
field names will span an entire row of the table used to render the field
list. 0 indicates "no limit". See also <a class="reference internal" href="#option-limit">option_limit</a>.</p>
<p>Default: 14 (i.e. 14 characters). Option: <tt class="docutils literal"><span class="pre">--field-name-limit</span></tt>.</p>
</div>
<div class="section" id="option-limit">
<h5><a class="toc-backref" href="#toc-entry-88">option_limit</a></h5>
<p>The maximum width (in characters) for options in <a class="reference external" href="../ref/rst/restructuredtext.html#option-lists">option lists</a>.
Longer options will span an entire row of the table used to render
the option list. 0 indicates "no limit".
See also <a class="reference internal" href="#field-name-limit">field_name_limit</a>.</p>
<p>Default: 14 (i.e. 14 characters). Option: <tt class="docutils literal"><span class="pre">--option-limit</span></tt>.</p>
</div>
</div>
<div class="section" id="html5-writer">
<h4><a class="toc-backref" href="#toc-entry-89">[html5 writer]</a></h4>
<p>The <a class="reference external" href="html.html#html5-polyglot">HTML5 Writer</a> generates valid XML that is compatible with <a class="reference external" href="https://www.w3.org/TR/2014/REC-html5-20141028/">HTML5</a>.
It shares all settings defined in the <a class="reference internal" href="#html-writers">[html writers]</a>
<a class="reference internal" href="#configuration-file-sections-entries">configuration section</a>.</p>
<p>New in Docutils 0.13.</p>
<div class="section" id="writer-specific-defaults-1">
<h5><a class="toc-backref" href="#toc-entry-90">Writer Specific Defaults</a></h5>
<dl class="docutils">
<dt><a class="reference internal" href="#initial-header-level">initial_header_level</a></dt>
<dd>2 (for "<h2>", cf. the "<a class="reference external" href="https://html.spec.whatwg.org/multipage/sections.html#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements">The h1, h2, h3, h4, h5, and h6 elements</a>"
in the HTML Standard)</dd>
<dt><a class="reference internal" href="#stylesheet-path-html-writers">stylesheet_path</a>:</dt>
<dd>"minimal.css, plain.css"</dd>
</dl>
</div>
<div class="section" id="embed-images">
<h5><a class="toc-backref" href="#toc-entry-91">embed_images</a></h5>
<p>Deprecated. Obsoleted by <a class="reference internal" href="#image-loading">image_loading</a>.</p>
</div>
<div class="section" id="image-loading">
<h5><a class="toc-backref" href="#toc-entry-92">image_loading</a></h5>
<p>Suggest at which point images should be loaded.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">embed:</th><td class="field-body">If the image can be read from the local file system,
the image data is embedded into the HTML document.</td>
</tr>
<tr class="field"><th class="field-name">link:</th><td class="field-body">Link to image in the HTML document (default).</td>
</tr>
<tr class="field"><th class="field-name">lazy:</th><td class="field-body">Link to image. Specify the <a class="reference external" href="https://html.spec.whatwg.org/multipage/urls-and-fetching.html#lazy-loading-attributes">lazy loading attribute</a> to defer
fetching the image.</td>
</tr>
</tbody>
</table>
<p>Default: "link". Option: <tt class="docutils literal"><span class="pre">--image-loading</span></tt>.</p>
<p>New in Docutils 0.18.</p>
</div>
<div class="section" id="section-self-link">
<h5><a class="toc-backref" href="#toc-entry-93">section_self_link</a></h5>
<p>Append an empty anchor element with a <tt class="docutils literal">href</tt> to the section to
section headings. See <tt class="docutils literal">responsive.css</tt> for an example how this can be
styled to show a symbol allowing users to copy the section's URL.</p>
<p>Default: disabled (False).
Options: <tt class="docutils literal"><span class="pre">--section-self-link</span></tt>, <tt class="docutils literal"><span class="pre">--no-section-self-link</span></tt>.</p>
<p>New in Docutils 0.18.</p>
</div>
</div>
<div class="section" id="pep-html-writer">
<h4><a class="toc-backref" href="#toc-entry-94">[pep_html writer]</a></h4>
<p>The PEP/HTML Writer derives from the HTML4/CSS1 Writer, and shares
all settings defined in the <a class="reference internal" href="#html-writers">[html writers]</a> and <a class="reference internal" href="#html4css1-writer">[html4css1 writer]</a>
<a class="reference internal" href="#configuration-file-sections-entries">configuration sections</a>.</p>
<div class="section" id="writer-specific-defaults-2">
<h5><a class="toc-backref" href="#toc-entry-95">Writer Specific Defaults</a></h5>
<dl class="docutils">
<dt><a class="reference internal" href="#initial-header-level">initial_header_level</a></dt>
<dd>1 (for "<h1>")</dd>
<dt><a class="reference internal" href="#stylesheet-path-html-writers">stylesheet_path</a>:</dt>
<dd>"pep.css"</dd>
<dt><a class="reference internal" href="#template-html-writers">template</a>:</dt>
<dd><tt class="docutils literal">docutils/writers/pep_html/template.txt</tt> in the installation
directory. For the exact machine-specific path, use the <tt class="docutils literal"><span class="pre">--help</span></tt>
option.</dd>
</dl>
</div>
<div class="section" id="no-random">
<h5><a class="toc-backref" href="#toc-entry-96">no_random</a></h5>
<p>Do not use a random banner image. Mainly used to get predictable
results when testing.</p>
<p>Default: random enabled (None). Options: <tt class="docutils literal"><span class="pre">--no-random</span></tt> (hidden).</p>
</div>
<div class="section" id="pep-home">
<h5><a class="toc-backref" href="#toc-entry-97">pep_home</a></h5>
<p>Home URL prefix for PEPs.</p>
<p>Default: current directory ("."). Option: <tt class="docutils literal"><span class="pre">--pep-home</span></tt>.</p>
</div>
<div class="section" id="python-home">
<h5><a class="toc-backref" href="#toc-entry-98">python_home</a></h5>
<p>Python's home URL.</p>
<p>Default: parent directory (".."). Option: <tt class="docutils literal"><span class="pre">--python-home</span></tt>.</p>
</div>
</div>
<div class="section" id="s5-html-writer">
<h4><a class="toc-backref" href="#toc-entry-99">[s5_html writer]</a></h4>
<p>The S5/HTML Writer derives from the HTML4/CSS1 Writer, and shares
all settings defined in the <a class="reference internal" href="#html-writers">[html writers]</a> and <a class="reference internal" href="#html4css1-writer">[html4css1 writer]</a>
<a class="reference internal" href="#configuration-file-sections-entries">configuration sections</a>.</p>
<div class="section" id="writer-specific-defaults-3">
<h5><a class="toc-backref" href="#toc-entry-100">Writer Specific Defaults</a></h5>
<dl class="docutils">
<dt><a class="reference internal" href="#compact-lists">compact_lists</a>:</dt>
<dd>disable compact lists.</dd>
<dt><a class="reference internal" href="#template-html-writers">template</a>:</dt>
<dd><tt class="docutils literal">docutils/writers/s5_html/template.txt</tt> in the installation
directory. For the exact machine-specific path, use the <tt class="docutils literal"><span class="pre">--help</span></tt>
option.</dd>
</dl>
</div>
<div class="section" id="hidden-controls">
<h5><a class="toc-backref" href="#toc-entry-101">hidden_controls</a></h5>
<p>Auto-hide the presentation controls in slideshow mode, or or keep
them visible at all times.</p>
<p>Default: auto-hide (True).
Options: <tt class="docutils literal"><span class="pre">--hidden-controls</span></tt>, <tt class="docutils literal"><span class="pre">--visible-controls</span></tt>.</p>
</div>
<div class="section" id="current-slide">
<h5><a class="toc-backref" href="#toc-entry-102">current_slide</a></h5>
<p>Enable or disable the current slide indicator ("1/15").</p>
<p>Default: disabled (None).
Options: <tt class="docutils literal"><span class="pre">--current-slide</span></tt>, <tt class="docutils literal"><span class="pre">--no-current-slide</span></tt>.</p>
</div>
<div class="section" id="overwrite-theme-files">
<h5><a class="toc-backref" href="#toc-entry-103">overwrite_theme_files</a></h5>
<p>Allow or prevent the overwriting of existing theme files in the
<tt class="docutils literal"><span class="pre">ui/<theme></span></tt> directory. This has no effect if "<a class="reference internal" href="#theme-url">theme_url</a>" is
used.</p>
<p>Default: keep existing theme files (None).
Options: <tt class="docutils literal"><span class="pre">--keep-theme-files</span></tt>, <tt class="docutils literal"><span class="pre">--overwrite-theme-files</span></tt>.</p>
</div>
<div class="section" id="theme">
<h5><a class="toc-backref" href="#toc-entry-104">theme</a></h5>
<p>Name of an installed S5 theme, to be copied into a <tt class="docutils literal"><span class="pre">ui/<theme></span></tt>
subdirectory, beside the destination file (output HTML). Note
that existing theme files will not be overwritten; the existing
theme directory must be deleted manually.
Also overrides the "<a class="reference internal" href="#theme-url">theme_url</a>" setting. <a class="footnote-reference" href="#override" id="footnote-reference-9">[5]</a></p>
<p>Default: "default". Option: <tt class="docutils literal"><span class="pre">--theme</span></tt>.</p>
</div>
<div class="section" id="theme-url">
<h5><a class="toc-backref" href="#toc-entry-105">theme_url</a></h5>
<p>The URL of an S5 theme directory. The destination file (output
HTML) will link to this theme; nothing will be copied. Also overrides
the "<a class="reference internal" href="#theme">theme</a>" setting. <a class="footnote-reference" href="#override" id="footnote-reference-10">[5]</a></p>
<p>Default: None. Option: <tt class="docutils literal"><span class="pre">--theme-url</span></tt>.</p>
</div>
<div class="section" id="view-mode">
<h5><a class="toc-backref" href="#toc-entry-106">view_mode</a></h5>
<p>The initial view mode, either "slideshow" or "outline".</p>
<p>Default: "slidewhow". Option: <tt class="docutils literal"><span class="pre">--view-mode</span></tt>.</p>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
</div>
</div>
</div>
<div class="section" id="latex-writers">
<h3><a class="toc-backref" href="#toc-entry-107">[latex writers]</a></h3>
<p>Common settings for the <a class="reference external" href="latex.html">LaTeX writers</a>
<a class="reference internal" href="#latex2e-writer">[latex2e writer]</a> and <a class="reference internal" href="#xetex-writer">[xetex writer]</a>.</p>
<div class="section" id="attribution-1">
<span id="attribution-latex-writers"></span><h4><a class="toc-backref" href="#toc-entry-108">attribution</a></h4>
<p>See <a class="reference internal" href="#attribution-html-writers">attribution [html writers]</a>.</p>
</div>
<div class="section" id="compound-enumerators">
<h4><a class="toc-backref" href="#toc-entry-109">compound_enumerators</a></h4>
<p>Enable or disable compound enumerators for nested <a class="reference external" href="../ref/rst/restructuredtext.html#enumerated-lists">enumerated lists</a>
(e.g. "1.2.a.ii").</p>
<p>Default: disabled (None).
Options: <tt class="docutils literal"><span class="pre">--compound-enumerators</span></tt>, <tt class="docutils literal"><span class="pre">--no-compound-enumerators</span></tt>.</p>
</div>
<div class="section" id="documentclass">
<h4><a class="toc-backref" href="#toc-entry-110">documentclass</a></h4>
<p>Specify LaTeX documentclass.</p>
<p>Default: "article". Option: <tt class="docutils literal"><span class="pre">--documentclass</span></tt>.</p>
</div>
<div class="section" id="documentoptions">
<h4><a class="toc-backref" href="#toc-entry-111">documentoptions</a></h4>
<p>Specify document options. Multiple options can be given, separated by
commas.</p>
<p>Default: "a4paper". Option: <tt class="docutils literal"><span class="pre">--documentoptions</span></tt>.</p>
</div>
<div class="section" id="docutils-footnotes">
<h4><a class="toc-backref" href="#toc-entry-112">docutils_footnotes</a></h4>
<p>Use the Docutils-specific macros <tt class="docutils literal">\DUfootnote</tt> and
<tt class="docutils literal">\DUfootnotetext</tt> for <a class="reference external" href="../ref/rst/restructuredtext.html#footnotes">footnotes</a>.</p>
<p>TODO: The alternative, "use_latex_footnotes" is not implemented yet.</p>
<p>Default: on. Option: <tt class="docutils literal"><span class="pre">--docutils-footnotes</span></tt>.</p>
</div>
<div class="section" id="embed-stylesheet-1">
<span id="embed-stylesheet-latex-writers"></span><h4><a class="toc-backref" href="#toc-entry-113">embed_stylesheet</a></h4>
<p>Embed the stylesheet(s) in the header of the output file. The
stylesheets must be accessible during processing. Currently, this
fails if the file is not available via the given path (i.e. the
file is <em>not</em> searched in the <a class="reference external" href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=what-TDS">TeX input path</a>).
See also <a class="reference internal" href="#embed-stylesheet-html-writers">embed_stylesheet [html writers]</a>.</p>
<p>Default: off. Options: <tt class="docutils literal"><span class="pre">--embed-stylesheet,</span> <span class="pre">--link-stylesheet</span></tt>.</p>
</div>
<div class="section" id="footnote-references-1">
<span id="footnote-references-latex-writers"></span><h4><a class="toc-backref" href="#toc-entry-114">footnote_references</a></h4>
<p>Format for <a class="reference external" href="../ref/rst/restructuredtext.html#footnote-references">footnote references</a>: one of "superscript" or "brackets".
See also <a class="reference internal" href="#footnote-references-html-writers">footnote_references [html writers]</a>.</p>
<p>Overrides <a class="footnote-reference" href="#override" id="footnote-reference-11">[5]</a> <a class="reference internal" href="#trim-footnote-reference-space">trim_footnote_reference_space</a>,
if the parser supports this option.</p>
<p>Default: "superscript". Option: <tt class="docutils literal"><span class="pre">--footnote-references</span></tt>.</p>
</div>
<div class="section" id="graphicx-option">
<h4><a class="toc-backref" href="#toc-entry-115">graphicx_option</a></h4>
<p>LaTeX graphicx package option.</p>
<p>Possible values are "dvips", "pdftex", "dvipdfmx".</p>
<p>Default: "". Option: <tt class="docutils literal"><span class="pre">--graphicx-option</span></tt>.</p>
</div>
<div class="section" id="hyperlink-color">
<h4><a class="toc-backref" href="#toc-entry-116">hyperlink_color</a></h4>
<p>Color of any hyperlinks embedded in text.</p>
<ul class="simple">
<li>"0" or "false" disable coloring of links. (Links will be marked
by red boxes that are not printed),</li>
<li>"black" results in “invisible“ links,</li>
</ul>
<p>Set <a class="reference internal" href="#hyperref-options">hyperref_options</a> to "draft" to completely disable hyperlinking.</p>
<p>Default: "blue". Option: <tt class="docutils literal"><span class="pre">--hyperlink-color</span></tt>.</p>
</div>
<div class="section" id="hyperref-options">
<h4><a class="toc-backref" href="#toc-entry-117">hyperref_options</a></h4>
<p>Options for the <a class="reference external" href="http://tug.org/applications/hyperref/">hyperref TeX package</a>. If <a class="reference internal" href="#hyperlink-color">hyperlink_color</a> is
not "false", the expansion of</p>
<pre class="literal-block">
'colorlinks=true,linkcolor=%s,urlcolor=%s' % (
hyperlink_color, self.hyperlink_color
</pre>
<p>is prepended.</p>
<p>Default: "". Option: <tt class="docutils literal"><span class="pre">--hyperref-options</span></tt>.</p>
</div>
<div class="section" id="latex-preamble">
<h4><a class="toc-backref" href="#toc-entry-118">latex_preamble</a></h4>
<p>LaTeX code that will be inserted in the document preamble.
Can be used to load packages with options or (re-) define LaTeX
macros without writing a custom style file (new in Docutils 0.7).</p>
<p>Default: writer dependent (see <a class="reference internal" href="#latex2e-writer">[latex2e writer]</a>, <a class="reference internal" href="#xetex-writer">[xetex writer]</a>).
Option: <tt class="docutils literal"><span class="pre">--latex-preamble</span></tt>.</p>
</div>
<div class="section" id="legacy-class-functions">
<h4><a class="toc-backref" href="#toc-entry-119">legacy_class_functions</a></h4>
<p>Use legacy functions <tt class="docutils literal">\DUtitle</tt> and <tt class="docutils literal">\DUadmonition</tt> with a
comma-separated list of class values as optional argument. If <cite>False</cite>, class
values are handled with wrappers and admonitions use the <tt class="docutils literal">DUadmonition</tt>
environment. See <a class="reference external" href="latex.html#classes">Generating LaTeX with Docutils</a> for details.</p>
<p>Default: False (changed in Docutils 0.18).
Options: <tt class="docutils literal"><span class="pre">--legacy-class-functions</span></tt>, <tt class="docutils literal"><span class="pre">--new-class-functions</span></tt>.</p>
<p>New in Docutils 0.17.</p>
</div>
<div class="section" id="legacy-column-widths">
<h4><a class="toc-backref" href="#toc-entry-120">legacy_column_widths</a></h4>
<p>Use "legacy algorithm" or new algorithm to determine table column widths.</p>
<p>The new algorithm limits the table width to the text width or specified
table width and keeps the ratio of specified column widths.</p>
<p>Custom table and/or column widths can be set with the respective options
of the <a class="reference external" href="../ref/rst/directives.html#table">table directive</a>. See also <a class="reference external" href="latex.html#table-style">Generating LaTeX with Docutils</a>.</p>
<p>Default: True (will change to False in 0.19).
Options: <tt class="docutils literal"><span class="pre">--legacy-column-widths</span></tt>, <tt class="docutils literal"><span class="pre">--new-column-widths</span></tt>.</p>
<p>New in Docutils 0.18.</p>
</div>
<div class="section" id="literal-block-env">
<h4><a class="toc-backref" href="#toc-entry-121">literal_block_env</a></h4>
<p>When possible<a class="footnote-reference" href="#footnote-2" id="footnote-reference-12">[3]</a>, use the specified environment for <a class="reference external" href="../ref/rst/restructuredtext.html#literal-blocks">literal blocks</a>.</p>
<p>Default: "" (quoting of whitespace and special chars).
Option: <tt class="docutils literal"><span class="pre">--literal-block-env</span></tt>.</p>
<table class="docutils footnote" frame="void" id="footnote-2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#footnote-reference-12">[3]</a></td><td>A literal-block element may originate from a <a class="reference external" href="../ref/rst/directives.html#parsed-literal">parsed literal</a>.
A LaTeX verbatim environment is only usable it does not contain
inline elements.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="reference-label">
<h4><a class="toc-backref" href="#toc-entry-122">reference_label</a></h4>
<p>Per default the latex-writer puts the reference title into
hyper references. Specify "ref*" or "pageref*" to get the section
number or the page number.</p>
<p>Default: "" (use hyper references). Option: <tt class="docutils literal"><span class="pre">--reference-label</span></tt>.</p>
</div>
<div class="section" id="section-enumerator-separator">
<h4><a class="toc-backref" href="#toc-entry-123">section_enumerator_separator</a></h4>
<p>The separator between section number prefix and enumerator for
compound enumerated lists (see <a class="reference internal" href="#compound-enumerators">compound_enumerators</a>).</p>
<p>Generally it isn't recommended to use both sub-sections and nested
enumerated lists with compound enumerators. This setting avoids
ambiguity in the situation where a section "1" has a list item
enumerated "1.1", and subsection "1.1" has list item "1". With a
separator of ".", these both would translate into a final compound
enumerator of "1.1.1". With a separator of "-", we get the
unambiguous "1-1.1" and "1.1-1".</p>
<p>Default: "-". Option: <tt class="docutils literal"><span class="pre">--section-enumerator-separator</span></tt>.</p>
</div>
<div class="section" id="section-prefix-for-enumerators">
<h4><a class="toc-backref" href="#toc-entry-124">section_prefix_for_enumerators</a></h4>
<p>Enable or disable section ("." subsection ...) prefixes for
compound enumerators. This has no effect unless
<a class="reference internal" href="#compound-enumerators">compound_enumerators</a> are enabled.</p>
<p>Default: disabled (None).
Options: <tt class="docutils literal"><span class="pre">--section-prefix-for-enumerators</span></tt>,
<tt class="docutils literal"><span class="pre">--no-section-prefix-for-enumerators</span></tt>.</p>
</div>
<div class="section" id="stylesheet-1">
<span id="stylesheet-latex-writers"></span><h4><a class="toc-backref" href="#toc-entry-125">stylesheet</a></h4>
<p>A comma-separated <a class="reference internal" href="#list">list</a> of style files.
See also <a class="reference internal" href="#stylesheet-html-writers">stylesheet [html writers]</a>.</p>
<p>Overrides also <a class="reference internal" href="#stylesheet-path-latex-writers">stylesheet_path</a>. <a class="footnote-reference" href="#override" id="footnote-reference-13">[5]</a></p>
<p>If <a class="reference internal" href="#embed-stylesheet-latex-writers">embed_stylesheet</a> is False (default), the stylesheet files are
referenced with <tt class="docutils literal">\usepackage</tt> (extension <tt class="docutils literal">.sty</tt> or no extension) or
<tt class="docutils literal">\input</tt> (any other extension).</p>
<p>LaTeX will search the specified files in the <a class="reference external" href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=what-TDS">TeX input path</a>.</p>
<p>Default: no stylesheet (""). Option: <tt class="docutils literal"><span class="pre">--stylesheet</span></tt>.</p>
</div>
<div class="section" id="stylesheet-dirs-1">
<span id="stylesheet-dirs-latex-writers"></span><h4><a class="toc-backref" href="#toc-entry-126">stylesheet_dirs</a></h4>
<p>A comma-separated list of directories where stylesheets can be found.
Used by the <a class="reference internal" href="#stylesheet-path-latex-writers">stylesheet_path</a> setting.</p>
<p>Note: This setting defines a "search path" (similar to the PATH variable for
executables). However, the term "path" is already used in the
<a class="reference internal" href="#stylesheet-path-latex-writers">stylesheet_path</a> setting with the meaning of a file location.</p>
<p>Default: the working directory of the process at launch and the directory
with default stylesheet files (writer and installation specific).
Use the <tt class="docutils literal"><span class="pre">--help</span></tt> option to get the exact value.
Option: <tt class="docutils literal"><span class="pre">--stylesheet-dirs</span></tt>.</p>
</div>
<div class="section" id="stylesheet-path-2">
<span id="stylesheet-path-latex-writers"></span><h4><a class="toc-backref" href="#toc-entry-127">stylesheet_path</a></h4>
<p>A comma-separated list of style files. Relative paths are expanded if a
matching file is found in the <a class="reference internal" href="#stylesheet-dirs-latex-writers">stylesheet_dirs</a>.
If <a class="reference internal" href="#embed-stylesheet-latex-writers">embed_stylesheet</a> is False, paths are rewritten relative to the
output file path. Run <tt class="docutils literal">latex</tt> from the directory containing
the output file.
See also <a class="reference internal" href="#stylesheet-path-html-writers">stylesheet_path [html writers]</a>.</p>
<p>The <a class="reference internal" href="#stylesheet-latex-writers">stylesheet</a> option is preferred for files in the <a class="reference external" href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=what-TDS">TeX input path</a>.</p>
<p>Also overrides <a class="reference internal" href="#stylesheet-latex-writers">stylesheet</a>. <a class="footnote-reference" href="#override" id="footnote-reference-14">[5]</a></p>
<p>Default: no stylesheet (""). Option: <tt class="docutils literal"><span class="pre">--stylesheet-path</span></tt>.</p>
</div>
<div class="section" id="table-style-1">
<span id="table-style-latex-writers"></span><h4><a class="toc-backref" href="#toc-entry-128">table_style</a></h4>
<p>Specify the default style for <a class="reference external" href="../ref/rst/restructuredtext.html#tables">tables</a>.
See also <a class="reference internal" href="#table-style-html-writers">table_style [html writers]</a>.</p>
<p>Supported values: "booktabs", "borderless", "colwidths-auto", and "standard".
See <a class="reference external" href="latex.html#tables">Generating LaTeX with Docutils</a> for details.</p>
<p>Default: "standard". Option: <tt class="docutils literal"><span class="pre">--table-style</span></tt>.</p>
</div>
<div class="section" id="template-1">
<span id="template-latex-writers"></span><h4><a class="toc-backref" href="#toc-entry-129">template</a></h4>
<p>Path <a class="footnote-reference" href="#pwd" id="footnote-reference-15">[4]</a> to template file, which must be encoded in UTF-8.
See also <a class="reference internal" href="#template-html-writers">template [html writers]</a>.</p>
<p>Default: writer dependent (see <a class="reference internal" href="#latex2e-writer">[latex2e writer]</a>, <a class="reference internal" href="#xetex-writer">[xetex writer]</a>).
Option: <tt class="docutils literal"><span class="pre">--template</span></tt>.</p>
</div>
<div class="section" id="use-bibtex">
<h4><a class="toc-backref" href="#toc-entry-130">use_bibtex</a></h4>
<p>Specify style and database for the experimental <cite>BibTeX</cite> support, for
example:</p>
<pre class="literal-block">
--use-bibtex=mystyle,mydb1,mydb2
</pre>
<p>Default: "" (don't use BibTeX). Option <tt class="docutils literal"><span class="pre">--use-bibtex</span></tt>.</p>
</div>
<div class="section" id="use-latex-abstract">
<h4><a class="toc-backref" href="#toc-entry-131">use_latex_abstract</a></h4>
<p>Use LaTeX abstract environment for the document's <a class="reference external" href="../ref/rst/restructuredtext.html#bibliographic-fields">abstract</a>.</p>
<p>Default: off. Options: <tt class="docutils literal"><span class="pre">--use-latex-abstract,</span> <span class="pre">--topic-abstract</span></tt>.</p>
</div>
<div class="section" id="use-latex-citations">
<h4><a class="toc-backref" href="#toc-entry-132">use_latex_citations</a></h4>
<p>Use cite for <a class="reference external" href="../ref/rst/restructuredtext.html#citations">citations</a> instead of a simulation with figure-floats.</p>
<p>Default: off. Options: <tt class="docutils literal"><span class="pre">--use-latex-citations,</span> <span class="pre">--figure-citations</span></tt>.</p>
</div>
<div class="section" id="use-latex-docinfo">
<h4><a class="toc-backref" href="#toc-entry-133">use_latex_docinfo</a></h4>
<p>Attach author and date to the <a class="reference external" href="../ref/rst/restructuredtext.html#document-title">document title</a>
instead of the <a class="reference external" href="../ref/rst/restructuredtext.html#bibliographic-fields">bibliographic fields</a>.</p>
<p>Default: off. Options: <tt class="docutils literal"><span class="pre">--use-latex-docinfo,</span> <span class="pre">--use-docutils-docinfo</span></tt>.</p>
</div>
<div class="section" id="use-latex-toc">
<h4><a class="toc-backref" href="#toc-entry-134">use_latex_toc</a></h4>
<p>To get page numbers in the <a class="reference external" href="../ref/rst/directives.html#contents">table of contents</a>, it
must be generated by LaTeX. Usually latex must be run twice to get
numbers correct.</p>
<p>Default: on. Options: <tt class="docutils literal"><span class="pre">--use-latex-toc,</span> <span class="pre">--use-docutils-toc</span></tt>.</p>
</div>
<div class="section" id="use-part-section">
<h4><a class="toc-backref" href="#toc-entry-135">use_part_section</a></h4>
<p>Add parts on top of the section hierarchy.</p>
<p>Default: don't (None). Option: <tt class="docutils literal"><span class="pre">--use-part-section</span></tt>.</p>
</div>
<div class="section" id="latex2e-writer">
<h4><a class="toc-backref" href="#toc-entry-136">[latex2e writer]</a></h4>
<p>The <a class="reference external" href="latex.html#latex2e-writer">LaTeX2e writer</a> generates a LaTeX source for compilation with 8-bit
LaTeX (<a class="reference external" href="https://www.tug.org/applications/pdftex/">pdfTeX</a>). It shares all settings defined in the <a class="reference internal" href="#latex-writers">[latex writers]</a>
<a class="reference internal" href="#configuration-file-sections-entries">configuration section</a>.</p>
<div class="section" id="writer-specific-defaults-4">
<h5><a class="toc-backref" href="#toc-entry-137">Writer Specific Defaults</a></h5>
<dl class="docutils">
<dt><a class="reference internal" href="#latex-preamble">latex_preamble</a></dt>
<dd><p class="first">Load the "PDF standard fonts" (Times, Helvetica, Courier):</p>
<pre class="last literal-block">
\usepackage{mathptmx} % Times
\usepackage[scaled=.90]{helvet}
\usepackage{courier}
</pre>
</dd>
<dt><a class="reference internal" href="#template-latex-writers">template</a></dt>
<dd>"default.tex" in the <tt class="docutils literal">docutils/writers/latex2e/</tt> directory
(installed automatically).</dd>
</dl>
</div>
<div class="section" id="font-encoding">
<h5><a class="toc-backref" href="#toc-entry-138">font_encoding</a></h5>
<p>Specify <a class="reference external" href="latex.html#font-encoding">LaTeX font encoding</a>. Multiple options can be given, separated by
commas. The last value becomes the document default.
Possible values are "", "T1", "OT1", "LGR,T1" or any other combination of
<a class="reference external" href="http://mirror.ctan.org/macros/latex/doc/encguide.pdf">LaTeX font encodings</a>.</p>
<p>Default: "T1". Option: <tt class="docutils literal"><span class="pre">--font-encoding</span></tt>.</p>
</div>
</div>
<div class="section" id="xetex-writer">
<h4><a class="toc-backref" href="#toc-entry-139">[xetex writer]</a></h4>
<p>The <a class="reference external" href="latex.html#xetex-writer">XeTeX writer</a> generates a LaTeX source for compilation with <a class="reference external" href="https://texfaq.org/FAQ-xetex-luatex">XeTeX or
LuaTeX</a>. It derives from the latex2e writer, and shares all settings
defined in the <a class="reference internal" href="#latex-writers">[latex writers]</a> and <a class="reference internal" href="#latex2e-writer">[latex2e writer]</a> <a class="reference internal" href="#configuration-file-sections-entries">configuration
sections</a>.</p>
<div class="section" id="writer-specific-defaults-5">
<h5><a class="toc-backref" href="#toc-entry-140">Writer Specific Defaults</a></h5>
<dl class="docutils">
<dt><a class="reference internal" href="#latex-preamble">latex_preamble</a>:</dt>
<dd><p class="first">Font setup for <a class="reference external" href="http://www.linuxlibertine.org/">Linux Libertine</a>,:</p>
<pre class="literal-block">
% Linux Libertine (free, wide coverage, not only for Linux)
\setmainfont{Linux Libertine O}
\setsansfont{Linux Biolinum O}
\setmonofont[HyphenChar=None]{DejaVu Sans Mono}
</pre>
<p class="last">The optional argument <tt class="docutils literal">HyphenChar=None</tt> to the monospace font
prevents word hyphenation in literal text.</p>
</dd>
</dl>
<dl class="docutils">
<dt><a class="reference internal" href="#template-latex-writers">template</a>:</dt>
<dd>"xelatex.tex" in the <tt class="docutils literal">docutils/writers/latex2e/</tt> directory
(installed automatically).<!-- TODO: show full path with ``- -help`` (like in the HTML writers)
and add the following line:
for the exact machine-specific path, use the ``- -help`` option). -->
</dd>
</dl>
</div>
</div>
</div>
<div class="section" id="odf-odt-writer">
<h3><a class="toc-backref" href="#toc-entry-141">[odf_odt writer]</a></h3>
<p>The following command line options are specific to <tt class="docutils literal">odtwriter</tt>:</p>
<div class="section" id="stylesheet-2">
<h4><a class="toc-backref" href="#toc-entry-142">stylesheet</a></h4>
<p>Specify a stylesheet URL, used verbatim.</p>
<p>Default: writers/odf_odt/styles.odt in the installation directory.</p>
</div>
<div class="section" id="odf-config-file">
<h4><a class="toc-backref" href="#toc-entry-143">odf-config-file</a></h4>
<p>Specify a configuration/mapping file relative to the current working
directory for additional ODF options. In particular, this file may
contain a section named "Formats" that maps default style names to names
to be used in the resulting output file allowing for adhering to external
standards. For more info and the format of the configuration/mapping
file, see the <a class="reference external" href="odt.html">Odt Writer for Docutils</a> document.</p>
</div>
<div class="section" id="cloak-email-addresses-1">
<h4><a class="toc-backref" href="#toc-entry-144">cloak-email-addresses</a></h4>
<p>Obfuscate email addresses to confuse harvesters while still
keeping email links usable with standards-compliant browsers.</p>
</div>
<div class="section" id="no-cloak-email-addresses">
<h4><a class="toc-backref" href="#toc-entry-145">no-cloak-email-addresses</a></h4>
<p>Do not obfuscate email addresses.</p>
</div>
<div class="section" id="table-border-thickness">
<h4><a class="toc-backref" href="#toc-entry-146">table-border-thickness</a></h4>
<p>Specify the thickness of table borders in thousands of a cm.
Default is 35.</p>
</div>
<div class="section" id="add-syntax-highlighting">
<h4><a class="toc-backref" href="#toc-entry-147">add-syntax-highlighting</a></h4>
<p>Add syntax highlighting in literal code blocks.</p>
</div>
<div class="section" id="no-syntax-highlighting">
<h4><a class="toc-backref" href="#toc-entry-148">no-syntax-highlighting</a></h4>
<p>Do not add syntax highlighting in literal code blocks.
(default)</p>
</div>
<div class="section" id="create-sections">
<h4><a class="toc-backref" href="#toc-entry-149">create-sections</a></h4>
<p>Create sections for headers. (default)</p>
</div>
<div class="section" id="no-sections">
<h4><a class="toc-backref" href="#toc-entry-150">no-sections</a></h4>
<p>Do not create sections for headers.</p>
</div>
<div class="section" id="create-links">
<h4><a class="toc-backref" href="#toc-entry-151">create-links</a></h4>
<p>Create links.</p>
</div>
<div class="section" id="no-links">
<h4><a class="toc-backref" href="#toc-entry-152">no-links</a></h4>
<p>Do not create links. (default)</p>
</div>
<div class="section" id="endnotes-end-doc">
<h4><a class="toc-backref" href="#toc-entry-153">endnotes-end-doc</a></h4>
<p>Generate endnotes at end of document, not footnotes at bottom of page.</p>
</div>
<div class="section" id="no-endnotes-end-doc">
<h4><a class="toc-backref" href="#toc-entry-154">no-endnotes-end-doc</a></h4>
<p>Generate footnotes at bottom of page, not endnotes at end of
document. (default)</p>
</div>
<div class="section" id="generate-list-toc">
<h4><a class="toc-backref" href="#toc-entry-155">generate-list-toc</a></h4>
<p>Generate a bullet list table of contents, not an
ODF/<tt class="docutils literal">oowriter</tt> table of contents.</p>
</div>
<div class="section" id="generate-oowriter-toc">
<h4><a class="toc-backref" href="#toc-entry-156">generate-oowriter-toc</a></h4>
<p>Generate an ODF/<tt class="docutils literal">oowriter</tt> table of contents, not a bullet
list. (default) <strong>Note:</strong> <tt class="docutils literal">odtwriter</tt> is not able to
determine page numbers, so you will need to open the generated
document in <tt class="docutils literal">oowriter</tt>, then right-click on the table of
contents and select "Update" to insert page numbers.</p>
</div>
<div class="section" id="custom-odt-header">
<h4><a class="toc-backref" href="#toc-entry-157">custom-odt-header</a></h4>
<p>Specify the contents of a custom header line. For details about
custom headers and about special field character sequences, see
section "Custom header/footers: inserting page numbers, date,
time, etc" in the <a class="reference external" href="odt.html">Odt Writer for Docutils</a> document for
details.</p>
</div>
<div class="section" id="custom-odt-footer">
<h4><a class="toc-backref" href="#toc-entry-158">custom-odt-footer</a></h4>
<p>Specify the contents of a custom footer line. For details about
custom footers and about special field character sequences, see
section "Custom header/footers: inserting page numbers, date,
time, etc" in the <a class="reference external" href="odt.html">Odt Writer for Docutils</a> document for
details.</p>
</div>
</div>
<div class="section" id="pseudoxml-writer">
<h3><a class="toc-backref" href="#toc-entry-159">[pseudoxml writer]</a></h3>
<div class="section" id="detailed">
<h4><a class="toc-backref" href="#toc-entry-160">detailed</a></h4>
<p>Pretty-print <#text> nodes.</p>
<p>Default: False. Option: <tt class="docutils literal"><span class="pre">--detailed</span></tt>.</p>
</div>
</div>
</div>
<div class="section" id="applications">
<h2><a class="toc-backref" href="#toc-entry-161">[applications]</a></h2>
<div class="section" id="buildhtml-application">
<h3><a class="toc-backref" href="#toc-entry-162">[buildhtml application]</a></h3>
<div class="section" id="dry-run">
<h4><a class="toc-backref" href="#toc-entry-163">dry_run</a></h4>
<p>Do not process files, show files that would be processed.</p>
<p>Default: False. Option: <tt class="docutils literal"><span class="pre">--dry-run</span></tt>.</p>
</div>
<div class="section" id="ignore">
<h4><a class="toc-backref" href="#toc-entry-164">ignore</a></h4>
<p><a class="reference internal" href="#list">List</a> of wildcard (shell globing) patterns, specifying files to silently
ignore. To specify multiple patterns, use colon-separated patterns (in
configuration files or on the command line); on the command line, the
option may also be used more than once.</p>
<p>Default: None. Option: <tt class="docutils literal"><span class="pre">--ignore</span></tt>.</p>
</div>
<div class="section" id="prune">
<h4><a class="toc-backref" href="#toc-entry-165">prune</a></h4>
<p><a class="reference internal" href="#list">List</a> of directories not to process. To specify multiple
directories, use colon-separated paths (in configuration files or
on the command line); on the command line, the option may also be
used more than once.</p>
<p>Default: ['.hg', '.bzr', '.git', '.svn', 'CVS']. Option:
<tt class="docutils literal"><span class="pre">--prune</span></tt>.</p>
</div>
<div class="section" id="recurse">
<h4><a class="toc-backref" href="#toc-entry-166">recurse</a></h4>
<p>Recursively scan subdirectories, or ignore subdirectories.</p>
<p>Default: recurse (True). Options: <tt class="docutils literal"><span class="pre">--recurse,</span> <span class="pre">--local</span></tt>.</p>
</div>
<div class="section" id="silent">
<h4><a class="toc-backref" href="#toc-entry-167">silent</a></h4>
<p>Work silently (no progress messages). Independent of
"report_level".</p>
<p>Default: show progress (None). Option: <tt class="docutils literal"><span class="pre">--silent</span></tt>.</p>
</div>
<div class="section" id="writer">
<span id="writer-buildhtml-application"></span><span id="html-writer"></span><h4><a class="toc-backref" href="#toc-entry-168">writer</a></h4>
<p><a class="reference external" href="html.html">HTML writer</a> version. One of "html", "html4", "html5".</p>
<p>Default: "html" (use Docutils' default HTML writer).
Option: <tt class="docutils literal"><span class="pre">--writer</span></tt></p>
<p>New in 0.17. Obsoletes the <tt class="docutils literal">html_writer</tt> option.</p>
</div>
</div>
<div class="section" id="docutils-application-1">
<h3><a class="toc-backref" href="#toc-entry-169">[docutils application]</a></h3>
<p>New in 0.17. Config file support added in 0.18.
Renamed in 0.19 (the old name "docutils-cli application" is kept as alias).
Support for reader/parser import names added in 0.19.</p>
<div class="section" id="reader">
<h4><a class="toc-backref" href="#toc-entry-170">reader</a></h4>
<p>Reader component name.
One of "standalone", "pep",
or the import name of a drop-in reader module.</p>
<p>Default: "standalone".
Option: <tt class="docutils literal"><span class="pre">--reader</span></tt></p>
</div>
<div class="section" id="parser">
<h4><a class="toc-backref" href="#toc-entry-171">parser</a></h4>
<p>Parser component name.
Either "rst" (default) or the import name of a drop-in parser module.</p>
<p>Parsers for <a class="reference external" href="https://spec.commonmark.org/0.30/">CommonMark</a> known to work with Docutils include "<a class="reference internal" href="#pycmark">pycmark</a>",
"<a class="reference internal" href="#myst">myst</a>", and "<a class="reference internal" href="#recommonmark">recommonmark</a>".</p>
<p>Default: "rst".
Option: <tt class="docutils literal"><span class="pre">--parser</span></tt></p>
</div>
<div class="section" id="writer-1">
<span id="writer-docutils-application"></span><h4><a class="toc-backref" href="#toc-entry-172">writer</a></h4>
<p>Writer component name.
One of "html", "html4", "html5", "latex", "xelatex", "odt", "xml",
"pseudoxml", "manpage", "pep_html", "s5", an alias,
or the import name of a drop-in writer module.</p>
<p>Default: "html5".
Option: <tt class="docutils literal"><span class="pre">--writer</span></tt></p>
</div>
</div>
</div>
<div class="section" id="other-settings">
<h2><a class="toc-backref" href="#toc-entry-173">Other Settings</a></h2>
<div class="section" id="command-line-only">
<h3><a class="toc-backref" href="#toc-entry-174">Command-Line Only</a></h3>
<p>These settings are only effective as command-line options; setting
them in configuration files has no effect.</p>
<div class="section" id="config">
<h4><a class="toc-backref" href="#toc-entry-175">config</a></h4>
<p>Path to a configuration file to read (if it exists). <a class="footnote-reference" href="#pwd" id="footnote-reference-16">[4]</a>
Settings may override defaults and earlier settings. The config
file is processed immediately. Multiple <tt class="docutils literal"><span class="pre">--config</span></tt> options may
be specified; each will be processed in turn.</p>
<p>Filesystem path settings contained within the config file will be
interpreted relative to the config file's location (<em>not</em> relative
to the current working directory).</p>
<p>Default: None. Option: <tt class="docutils literal"><span class="pre">--config</span></tt>.</p>
</div>
</div>
<div class="section" id="internal-settings">
<h3><a class="toc-backref" href="#toc-entry-176">Internal Settings</a></h3>
<p>These settings are for internal use only; setting them in
configuration files has no effect, and there are no corresponding
command-line options.</p>
<div class="section" id="config-files">
<h4><a class="toc-backref" href="#toc-entry-177">_config_files</a></h4>
<p>List of paths of applied configuration files.</p>
<p>Default: None. No command-line options.</p>
</div>
<div class="section" id="directories">
<h4><a class="toc-backref" href="#toc-entry-178">_directories</a></h4>
<p>(<tt class="docutils literal">buildhtml.py</tt> front end.) List of paths to source
directories, set from positional arguments.</p>
<p>Default: current working directory (None). No command-line
options.</p>
</div>
<div class="section" id="disable-config">
<h4><a class="toc-backref" href="#toc-entry-179">_disable_config</a></h4>
<p>Prevent standard configuration files from being read. For
programmatic use only.</p>
<p>Default: config files enabled (None). No command-line options.</p>
</div>
<div class="section" id="destination">
<h4><a class="toc-backref" href="#toc-entry-180">_destination</a></h4>
<p>Path to output destination, set from positional arguments.</p>
<p>Default: stdout (None). No command-line options.</p>
</div>
<div class="section" id="source">
<h4><a class="toc-backref" href="#toc-entry-181">_source</a></h4>
<p>Path to input source, set from positional arguments.</p>
<p>Default: stdin (None). No command-line options.</p>
<hr class="docutils" />
<table class="docutils footnote" frame="void" id="pwd" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[4]</td><td><em>(<a class="fn-backref" href="#footnote-reference-2">1</a>, <a class="fn-backref" href="#footnote-reference-3">2</a>, <a class="fn-backref" href="#footnote-reference-8">3</a>, <a class="fn-backref" href="#footnote-reference-15">4</a>, <a class="fn-backref" href="#footnote-reference-16">5</a>)</em> Path relative to the working directory of the process at
launch.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="override" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[5]</td><td><em>(<a class="fn-backref" href="#footnote-reference-5">1</a>, <a class="fn-backref" href="#footnote-reference-6">2</a>, <a class="fn-backref" href="#footnote-reference-7">3</a>, <a class="fn-backref" href="#footnote-reference-9">4</a>, <a class="fn-backref" href="#footnote-reference-10">5</a>, <a class="fn-backref" href="#footnote-reference-11">6</a>, <a class="fn-backref" href="#footnote-reference-13">7</a>, <a class="fn-backref" href="#footnote-reference-14">8</a>)</em> The overridden setting will automatically be set to
<tt class="docutils literal">None</tt> for command-line options and config file settings. Client
programs which specify defaults that override other settings must
do the overriding explicitly, by assigning <tt class="docutils literal">None</tt> to the other
settings.</td></tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="section" id="old-format-configuration-files">
<h1><a class="toc-backref" href="#toc-entry-182">Old-Format Configuration Files</a></h1>
<p>Formerly, Docutils configuration files contained a single "[options]"
section only. This was found to be inflexible, and in August 2003
Docutils adopted the current component-based configuration file
sections as described above.
Up to version 2.0, Docutils will still recognize the old "[options]"
section, but complain with a deprecation warning.</p>
<p>To convert existing config files, the easiest way is to change the
section title: change "[options]" to "[general]". Most settings
haven't changed. The only ones to watch out for are these:</p>
<table border="1" class="docutils">
<colgroup>
<col width="36%" />
<col width="64%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Old-Format Setting</th>
<th class="head">New Section & Setting</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>pep_stylesheet</td>
<td>[pep_html writer] stylesheet</td>
</tr>
<tr><td>pep_stylesheet_path</td>
<td>[pep_html writer] stylesheet_path</td>
</tr>
<tr><td>pep_template</td>
<td>[pep_html writer] template</td>
</tr>
</tbody>
</table>
<!-- References -->
</div>
</div>
</body>
</html>