---
name: "rst2html5"
section: "1"
platform: "linux"
package: "docutils-common"
version: "0.21.2+dfsg-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/rst2html5"
---

# rst2html5(1)

convert reST documents to HTML 5

## NAME

rst2html5 - convert reST documents to HTML 5

## SYNOPSIS

rst2html5 \[options\] \[\<source\> \[\<destination\>\]\]

## DESCRIPTION

Generate HTML5 documents from standalone reStructuredText sources \< \<https://docutils.sourceforge.io/docs/user/html.html#html5-polyglot\> \>.  Reads from \<source\> (default is stdin) and writes to \<destination\> (default is stdout).  See  \<https://docutils.sourceforge.io/docs/user/config.html\>  for a detailed settings reference.

## OPTIONS

### General Docutils Options

- **--output=***\<destination\>*

  Output destination name. Obsoletes the \<destination\> positional argument. Default: None (stdout).

- **--title=***\<title\>*

  Specify the document title as metadata.

- **--generator, -g**

  Include a "Generated by Docutils" credit and link.

- **--no-generator**

  Do not include a generator credit.

- **--date, -d**

  Include the date at the end of the document (UTC).

- **--time, -t**

  Include the time & date (UTC).

- **--no-datestamp**

  Do not include a datestamp of any kind.

- **--root-prefix=***\<path\>*

  Base directory for absolute paths when reading from the local filesystem. Default "/".

- **--source-link, -s**

  Include a "View document source" link.

- **--source-url=***\<URL\>*

  Use \<URL\> for a source link; implies --source-link.

- **--no-source-link**

  Do not include a "View document source" link.

- **--toc-entry-backlinks**

  Link from section headers to TOC entries.  (default)

- **--toc-top-backlinks**

  Link from section headers to the top of the TOC.

- **--no-toc-backlinks**

  Disable backlinks to the table of contents.

- **--footnote-backlinks**

  Link from footnotes/citations to references. (default)

- **--no-footnote-backlinks**

  Disable backlinks from footnotes and citations.

- **--section-numbering**

  Enable section numbering by Docutils.  (default)

- **--no-section-numbering**

  Disable section numbering by Docutils.

- **--strip-comments**

  Remove comment elements from the document tree.

- **--leave-comments**

  Leave comment elements in the document tree. (default)

- **--strip-elements-with-class=***\<class\>*

  Remove all elements with classes="\<class\>" from the document tree. Warning: potentially dangerous; use with caution. (Multiple-use option.)

- **--strip-class=***\<class\>*

  Remove all classes="\<class\>" attributes from elements in the document tree. Warning: potentially dangerous; use with caution. (Multiple-use option.)

- **--report=***\<level\>,* **-r** *\<level\>*

  Report system messages at or higher than \<level\>: "info" or "1", "warning"/"2" (default), "error"/"3", "severe"/"4", "none"/"5"

- **--verbose, -v**

  Report all system messages.  (Same as "--report=1".)

- **--quiet, -q**

  Report no system messages.  (Same as "--report=5".)

- **--halt=***\<level\>*

  Halt execution at system messages at or above \<level\>. Levels as in --report.  Default: 4 (severe).

- **--strict**

  Halt at the slightest problem.  Same as "--halt=info".

- **--exit-status=***\<level\>*

  Enable a non-zero exit status for non-halting system messages at or above \<level\>.  Default: 5 (disabled).

- **--debug**

  Enable debug-level system messages and diagnostics.

- **--no-debug**

  Disable debug output.  (default)

- **--warnings=***\<file\>*

  Send the output of system messages to \<file\>.

- **--traceback**

  Enable Python tracebacks when Docutils is halted.

- **--no-traceback**

  Disable Python tracebacks.  (default)

- **--input-encoding=***\<name\[:handler\]\>,* **-i** *\<name\[:handler\]\>*

  Specify the encoding and optionally the error handler of input text.  Default: \<auto-detect\>:strict.

- **--input-encoding-error-handler=***INPUT\_ENCODING\_ERROR\_HANDLER*

  Specify the error handler for undecodable characters. Choices: "strict" (default), "ignore", and "replace".

- **--output-encoding=***\<name\[:handler\]\>,* **-o** *\<name\[:handler\]\>*

  Specify the text encoding and optionally the error handler for output.  Default: utf-8:strict.

- **--output-encoding-error-handler=***OUTPUT\_ENCODING\_ERROR\_HANDLER*

  Specify error handler for unencodable output characters; "strict" (default), "ignore", "replace", "xmlcharrefreplace", "backslashreplace".

- **--error-encoding=***\<name\[:handler\]\>,* **-e** *\<name\[:handler\]\>*

  Specify text encoding and optionally error handler for error output.  Default text encoding: system encoding. Default error handler: backslashreplace.

- **--error-encoding-error-handler=***ERROR\_ENCODING\_ERROR\_HANDLER*

  Specify the error handler for unencodable characters in error output.  Default: backslashreplace.

- **--language=***\<name\>,* **-l** *\<name\>*

  Specify the language (as BCP 47 language tag). Default: en.

- **--record-dependencies=***\<file\>*

  Write output file dependencies to \<file\>.

- **--config=***\<file\>*

  Read configuration settings from \<file\>, if it exists.

- **--version, -V**

  Show this program's version number and exit.

- **--help, -h**

  Show this help message and exit.

### Generic Parser Options

- **--no-file-insertion**

  Disable directives that insert the contents of an external file; replaced with a "warning" system message.

- **--file-insertion-enabled**

  Enable directives that insert the contents of an external file. (default)

- **--no-raw**

  Disable the "raw" directive; replaced with a "warning" system message.

- **--raw-enabled**

  Enable the "raw" directive. (default)

- **--line-length-limit=***\<length\>*

  Maximal number of characters in an input line. Default 10 000.

### reStructuredText Parser Options

- **--pep-references**

  Recognize and link to standalone PEP references (like "PEP 258").

- **--pep-base-url=***\<URL\>*

  Base URL for PEP references (default " \<https://peps.python.org/\> ").

- **--pep-file-url-template=***\<URL\>*

  Template for PEP file part of URL. (default "pep-%04d")

- **--rfc-references**

  Recognize and link to standalone RFC references (like "RFC 822").

- **--rfc-base-url=***\<URL\>*

  Base URL for RFC references (default " \<https://tools.ietf.org/html/\> ").

- **--tab-width=***\<width\>*

  Set number of spaces for tab expansion (default 8).

- **--trim-footnote-reference-space**

  Remove spaces before footnote references.

- **--leave-footnote-reference-space**

  Leave spaces before footnote references.

- **--syntax-highlight=***\<format\>*

  Token name set for parsing code with Pygments: one of "long", "short", or "none" (no parsing). Default is "long".

- **--smart-quotes=***\<yes/no/alt\>*

  Change straight quotation marks to typographic form: one of "yes", "no", "alt\[ernative\]" (default "no").

- **--smartquotes-locales=***\<language:quotes\[,language:quotes,...\]\>*

  Characters to use as "smart quotes" for \<language\>.

- **--word-level-inline-markup**

  Inline markup recognized at word boundaries only (adjacent to punctuation or whitespace). Force character-level inline markup recognition with "" (backslash + space). Default.

- **--character-level-inline-markup**

  Inline markup recognized anywhere, regardless of surrounding characters. Backslash-escapes must be used to avoid unwanted markup recognition. Useful for East Asian languages. Experimental.

### Standalone Reader Options

- **--no-doc-title**

  Disable the promotion of a lone top-level section title to document title (and subsequent section title to document subtitle promotion; enabled by default).

- **--no-doc-info**

  Disable the bibliographic field list transform (enabled by default).

- **--section-subtitles**

  Activate the promotion of lone subsection titles to section subtitles (disabled by default).

- **--no-section-subtitles**

  Deactivate the promotion of lone subsection titles.

### HTML Writer Options

- **--template=***\<file\>*

  Template file. (UTF-8 encoded, default: "/usr/share/do cutils/writers/html5\_polyglot/template.txt")

- **--stylesheet=***\<URL\[,URL,...\]\>*

  Comma separated list of stylesheet URLs. Overrides previous --stylesheet and --stylesheet-path settings.

- **--stylesheet-path=***\<file\[,file,...\]\>*

  Comma separated list of stylesheet paths. Relative paths are expanded if a matching file is found in the --stylesheet-dirs. With --link-stylesheet, the path is rewritten relative to the output HTML file. (default: "minimal.css,plain.css")

- **--stylesheet-dirs=***\<dir\[,dir,...\]\>*

  Comma-separated list of directories where stylesheets are found. Used by --stylesheet-path when expanding relative path arguments. (default: ".,/usr/share/docutils/writers/html5\_polyglot")

- **--embed-stylesheet**

  Embed the stylesheet(s) in the output HTML file.  The stylesheet files must be accessible during processing. (default)

- **--link-stylesheet**

  Link to the stylesheet(s) in the output HTML file.

- **--initial-header-level=***\<level\>*

  Specify the initial header level. Does not affect document title & subtitle (see --no-doc-title). (default: 2 for "\<h2\>")

- **--footnote-references=***\<format\>*

  Format for footnote references: one of "superscript" or "brackets". (default: "brackets")

- **--attribution=***\<format\>*

  Format for block quote attributions: one of "dash" (em-dash prefix), "parentheses"/"parens", or "none". (default: "dash")

- **--compact-lists**

  Remove extra vertical whitespace between items of "simple" bullet lists and enumerated lists. (default)

- **--no-compact-lists**

  Disable compact simple bullet and enumerated lists.

- **--compact-field-lists**

  Remove extra vertical whitespace between items of simple field lists. (default)

- **--no-compact-field-lists**

  Disable compact simple field lists.

- **--table-style=***TABLE\_STYLE*

  Added to standard table classes. Defined styles: borderless, booktabs, align-left, align-center, align- right, colwidths-auto, colwidths-grid.

- **--math-output=***MATH\_OUTPUT*

  Math output format (one of "MathML", "HTML", "MathJax", or "LaTeX") and option(s). (default: "HTML math.css")

- **--xml-declaration**

  Prepend an XML declaration.

- **--no-xml-declaration**

  Omit the XML declaration (default).

- **--cloak-email-addresses**

  Obfuscate email addresses to confuse harvesters while still keeping email links usable with standards- compliant browsers.

### HTML5 Writer Options

- **--image-loading=***IMAGE\_LOADING*

  Suggest at which point images should be loaded: "embed", "link" (default), or "lazy".

- **--section-self-link**

  Append a self-link to section headings.

- **--no-section-self-link**

  Do not append a self-link to section headings. (default)