rst2html5(1)

📦
version 0.23 · 6 versions
, in ubuntu stonking

🎀 NAME 🎀

hi bestie, this is the manual page for rst2html5(1) — the little icon who turns reST documents into HTML 5. she's lowkey iconic and you're about to be obsessed. 🌸

✨ SYNOPSIS ✨

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

💖 DESCRIPTION 💖

okay so rst2html5 generates HTML5 documents from standalone reStructuredText sources — the polyglot HTML5 situation, documented right here: https://docutils.sourceforge.io/docs/user/html.html#html5-polyglot. 💅

she reads from <source> (default is stdin) and writes to <destination> (default is stdout). no cap.

and if you want the whole detailed settings reference, it's giving https://docutils.sourceforge.io/docs/user/config.html. go read it, i'll wait. 🫶

🦋 OPTIONS 🦋

🌈 General Docutils Options 🌈

  • --output-path=<destination>, --output=<destination> — names where the output goes. this one obsoletes the <destination> positional argument, so it's the glow-up version. default: None (stdout).
  • --title=<title> — set the document title as metadata.
  • --generator, -g — add a "Generated by Docutils" credit plus a link. credit where credit's due 💅
  • --no-generator — no generator credit. we're being humble today.
  • --date, -d — drop the date at the end of the document (UTC).
  • --time, -t — include the time and the date (UTC).
  • --no-datestamp — no datestamp of any kind. zero. nada.
  • --root-prefix=<path> — the base directory for absolute paths when reading from the local filesystem. default "".
  • --source-link, -s — add a "View document source" link.
  • --source-url=<URL> — use <URL> for a source link. this one implies --source-link, it comes as a package deal ✨
  • --no-source-link — no "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. bye 👋
  • --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>, where the levels are: "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".) shhh 🤫
  • --halt=<level> — halt execution at system messages at or above <level>. levels work like --report. default: 4 (severe).
  • --strict — halt at the slightest problem. same as "--halt=info". she does not play.
  • --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]> — specify the encoding, and optionally the error handler, of input text. default: utf-8.
  • --output-encoding=<name[:handler]> — specify the text encoding, and optionally the error handler, for output. default: utf-8.
  • --error-encoding=<name[:handler]>, -e <name[:handler]> — specify text encoding, and optionally the error handler, for error output. default: system encoding.
  • --language=<tag>, -l <tag> — specify the language (as a 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; they get 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.
  • --legacy-ids — keep identifiers backwards compatible. default.
  • --matching-ids — explicit targets use identifiers matching the reference name.
  • --validate — validate the document tree after parsing.
  • --no-validation — do not validate the document tree. (default)

💜 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 the PEP file part of the 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 the 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"). the curly quotes glow-up ✨
  • --smartquotes-locales=<language:quotes[,language:quotes,...]> — the 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 the 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/docutils/writers/html5_polyglot/template.txt")
  • --stylesheet=<URL[,URL,...]> — comma separated list of stylesheet URLs. overrides previous --stylesheet and --stylesheet-path settings. she said overrides. 💅
  • --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=<style> — class value(s) assigned to all tables. defined styles: borderless, booktabs, align-left, align-center, align-right, colwidths-auto, colwidths-grid.
  • --math-output=<format[option(s)]> — math output format (one of "MathML", "HTML", "MathJax", or "LaTeX") and option(s). (default: "MathML")
  • --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. sneaky but make it cute 🙈

🦄 HTML5 Writer Options 🦄

  • --image-loading=<strategy> — 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)

that's the whole page, bestie, no notes 💖 and if you scrolled all the way down here just to see the footer, it's just rst2html5(1) looking back at you — same name, same page, serving cunt and documentation in equal measure. slay, periodt, go convert something gorgeous. 🌈✨🫶

📦 where this page comes from