docutils(1)

📦
version 0.23 · 5 versions
, in ubuntu stonking

💖 NAME 💖

okay bestie, so docutils is the generic command line interface for the docutils package ✨ that's the whole vibe, that's the assignment 🎀

🦋 SYNOPSIS 🦋

docutils [options] [<source> [<destination>]]

🌸 DESCRIPTION 🌸

no cap, this thing converts documents into useful formats 💅 like that's literally its whole job and it ate fr fr 👑

here's the tea on how it flows 🫖 it reads from <source> — and if you don't hand it a source, bestie, it defaults to stdin 🙈 — and then it writes to <destination> — and if you don't give it one of those either, it defaults to stdout 💖 so like, no args and it's still gonna pipe the goods straight through, iconic behavior tbh ✨

🧚 quick heads up: if you want the detailed settings reference (like the full deep dive, iykyk), it's chillin' at https://docutils.sourceforge.io/docs/user/config.html 🌈 go look, it's giving very thorough 📚

💅 OPTIONS 💅

bestie this is the ✨main character✨ section. every flag, every default, every little caveat, all of it. it's giving "wall of text" but honestly? iconic. grab a snack 🍓

🎀 General Docutils Options 🎀

  • --output-path=<destination>, --output=<destination> — 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 — drops in a "Generated by Docutils" credit and link, so everyone knows who did it 💅
  • --no-generator — no generator credit. we're being mysterious.
  • --date, -d — slaps the date at the end of the document (UTC).
  • --time, -t — time and date at the end (UTC).
  • --no-datestamp — no datestamp of any kind. zero. nada.
  • --root-prefix=<path> — base directory for absolute paths when you're reading from the local filesystem. Default "".
  • --source-link, -s — adds a "View document source" link.
  • --source-url=<URL> — use <URL> for the source link. heads up, this one implies --source-link automatically.
  • --no-source-link — no "View document source" link, periodt.
  • --toc-entry-backlinks — links from section headers back to TOC entries. (this is the default, bestie)
  • --toc-top-backlinks — links from section headers to the top of the TOC instead.
  • --no-toc-backlinks — kills the backlinks to the table of contents.
  • --footnote-backlinks — links from footnotes/citations to their references. (default!)
  • --no-footnote-backlinks — no backlinks from footnotes and citations.
  • --section-numbering — turns on section numbering by Docutils. (default)
  • --no-section-numbering — turns section numbering off.
  • --strip-comments — removes comment elements from the document tree.
  • --leave-comments — leaves comment elements right where they are. (default)
  • --strip-elements-with-class=<class> — removes all elements with classes="<class>" from the document tree. > ⚠️ Warning: potentially dangerous; use with caution. (Multiple-use option.)
  • --strip-class=<class> — removes 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>. your 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 zero system messages. same as "--report=5".
  • --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 energy as "--halt=info". very dramatic, very valid.
  • --exit-status=<level> — enables a non-zero exit status for non-halting system messages at or above <level>. Default: 5 (disabled).
  • --debug — enables debug-level system messages and diagnostics. 🐛
  • --no-debug — disables debug output. (default)
  • --warnings=<file> — sends the output of system messages to <file>.
  • --traceback — enables Python tracebacks when Docutils is halted.
  • --no-traceback — disables Python tracebacks. (default)
  • --input-encoding=<name[:handler]> — specify the encoding and optionally the error handler for 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. bye! 🦋
  • --help, -h — show this help message and exit.

🌸 Generic Parser Options 🌸

  • --no-file-insertion — disables directives that insert the contents of an external file; they get replaced with a "warning" system message.
  • --file-insertion-enabled — enables directives that insert the contents of an external file. (default)
  • --no-raw — disables the "raw" directive; replaced with a "warning" system message.
  • --raw-enabled — enables the "raw" directive. (default)
  • --line-length-limit=<length> — maximal number of characters in an input line. Default 10 000.
  • --legacy-ids — keeps identifiers backwards compatible. Default.
  • --matching-ids — explicit targets use identifiers matching the reference name.
  • --validate — validates the document tree after parsing. 🔍
  • --no-validation — does not validate the document tree. (default)

🦋 reStructuredText Parser Options 🦋

  • --pep-references — recognizes standalone PEP references (like "PEP 258") and links them up. 🔗
  • --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 — recognizes standalone RFC references (like "RFC 822") and links them.
  • --rfc-base-url=<URL> — base URL for RFC references (default "https://tools.ietf.org/html/").
  • --tab-width=<width> — sets the number of spaces for tab expansion (default 8).
  • --trim-footnote-reference-space — removes spaces before footnote references.
  • --leave-footnote-reference-space — leaves spaces before footnote references alone.
  • --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> — changes straight quotation marks into typographic form: one of "yes", "no", "alt[ernative]" (default "no").
  • --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 "" (that's backslash + space, bestie). 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 — disables the promotion of a lone top-level section title to document title (and the chain reaction where the next section title gets promoted to document subtitle; that's enabled by default).
  • --no-doc-info — disables the bibliographic field list transform (enabled by default).
  • --section-subtitles — activates the promotion of lone subsection titles to section subtitles (disabled by default).
  • --no-section-subtitles — deactivates 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. this one overrides any previous --stylesheet and --stylesheet-path settings. it said what it said.
  • --stylesheet-path=<file[,file,...]> — comma separated list of stylesheet paths. relative paths get 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 — embeds the stylesheet(s) in the output HTML file. the stylesheet files must be accessible during processing. (default)
  • --link-stylesheet — links 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 — removes extra vertical whitespace between items of "simple" bullet lists and enumerated lists. (default)
  • --no-compact-lists — disables compact simple bullet and enumerated lists.
  • --compact-field-lists — removes extra vertical whitespace between items of simple field lists. (default)
  • --no-compact-field-lists — disables 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 — prepends an XML declaration.
  • --no-xml-declaration — omits the XML declaration (default).
  • --cloak-email-addresses — obfuscates email addresses to confuse harvesters while still keeping email links usable with standards-compliant browsers. sneaky but make it ✨classy✨

🫶 HTML5 Writer Options 🫶

  • --image-loading=<strategy> — suggests at which point images should be loaded: "embed", "link" (default), or "lazy". the lazy girlies ate with this one 🦋
  • --section-self-link — appends a self-link to section headings.
  • --no-section-self-link — does not append a self-link to section headings. (default)

👑 Docutils Application Options 👑

Reader, writer, and parser settings influence the available options. Example: use --help --writer=latex to see LaTeX writer options. iykyk 💅
  • --reader=<reader> — reader name (currently: "standalone").
  • --parser=<parser> — parser name (currently: "rst").
  • --writer=<writer> — writer name (currently: "html5").

and that's the whole page, bestie 💖 you made it to the very bottom — truly main character behavior. this was the docutils(1) manual page, footer and all, and yes the footer in the source is just the little docutils(1) tag sitting there at the end of the version-and-date line like a signature. no cap, go forth and render some documents ✨🌈

📦 where this page comes from