MYSTNB-DOCUTILS-HTML5(1)

✨ NAME ✨

mystnb-docutils-html5 — mystnb-docutils-html5, the main-character command of this MYSTNB-DOCUTILS-HTML5(1) User Commands manual page. That’s the whole NAME vibe, bestie 💅

---

🌸 DESCRIPTION 🌸

Okay so, this is the command that generates HTML5 documents from standalone MyST Notebook sources. It reads from <source> — default is stdin — and writes to <destination> — default is stdout. No cap, that’s the core glow-up ✨

See https://docutils.sourceforge.io/docs/user/config.html for a detailed settings reference. External outputs are written to --nb-output-folder 🫶

🌀 Usage

mystnb-docutils-html5 [options] [<source> [<destination>]]

🌈 Options

💖 General Docutils Options

• --output-path=<destination>, --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]> — 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 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.

🪄 MyST-NB options

• --nb-read-as-md=<boolean> — Read as the MyST Markdown format (default: False).
• --nb-metadata-key=<str> — Notebook level metadata key for config overrides (default: (default: 'mystnb')).
• --nb-cell-metadata-key=<str> — Cell level metadata key for config overrides (default: (default: 'mystnb')).
• --nb-eval-name-regex=<str> — Regex that matches permitted values of eval expressions (default: (default: '^[a-zAZ_][a-zA-Z0-9_]*$')).
• --nb-execution-mode=<'off'|'force'|'auto'|'cache'|'inline'> — Execution mode for notebooks (default: 'auto').
• --nb-execution-cache-path=<str> — Path to folder for caching notebooks (default: <outdir>) (default: (default: '')).
• --nb-execution-timeout=<int> — Execution timeout (seconds) (default: 30).
• --nb-execution-in-temp=<boolean> — Use temporary folder for the execution current working directory (default: False).
• --nb-execution-allow-errors=<boolean> — Allow errors during execution (default: False).
• --nb-execution-raise-on-error=<boolean> — Raise an exception on failed execution, rather than emitting a warning (default: False).
• --nb-execution-show-tb=<boolean> — Print traceback to stderr on execution error (default: False).
• --nb-merge-streams=<boolean> — Merge all stdout execution output streams; same with stderr (default: False).
• --nb-render-plugin=<str> — The entry point for the execution output render class (in group myst_nb.output_renderer) (default: (default: 'default')).
• --nb-remove-code-source=<boolean> — Remove code cell source (default: False).
• --nb-remove-code-outputs=<boolean> — Remove code cell outputs (default: False).
• --nb-scroll-outputs=<boolean> — Make long cell outputs scrollable (default: False).
• --nb-code-prompt-show=<str> — Prompt to expand hidden code cell {content|source|outputs} (default: (default: 'Show code cell {type}')).
• --nb-code-prompt-hide=<str> — Prompt to collapse hidden code cell {content|source|outputs} (default: (default: 'Hide code cell {type}')).
• --nb-number-source-lines=<boolean> — Number code cell source lines (default: False).
• --nb-builder-name=<str> — Builder name, to select render priority for mime types (default: (default: 'html')).
• --nb-output-stderr=<'show'|'remove'|'remove-warn'|'warn'|'error'|'severe'> — Behaviour for stderr output (default: 'show').
• --nb-render-text-lexer=<str> — Pygments lexer applied to stdout/stderr and text/plain outputs (default: (default: 'myst-ansi')).
• --nb-render-error-lexer=<str> — Pygments lexer applied to error/traceback outputs (default: (default: 'ipythontb')).
• --nb-render-markdown-format=<'commonmark'|'gfm'|'myst'> — The format to use for text/markdown rendering (default: 'commonmark').
• --nb-output-folder=<str> — Folder for external outputs (like images), skipped if empty (default: (default: 'build')).
• --nb-append-css=<boolean> — Add default MyST-NB CSS to HTML outputs (default: True).
• --nb-metadata-to-fm=<boolean> — Convert unhandled metadata to frontmatter (default: False).

🧚 MyST options

• --myst-commonmark-only=<boolean> — Use strict CommonMark parser (default: False).
• --myst-gfm-only=<boolean> — Use strict Github Flavoured Markdown parser (default: False).
• --myst-enable-extensions=<comma-delimited> — Enable syntax extensions.
• --myst-disable-syntax=<comma-delimited> — Disable Commonmark syntax elements.
• --myst-all-links-external=<boolean> — Parse all links as simple hyperlinks (default: False).
• --myst-links-external-new-tab=<boolean> — Open all external links in a new tab (default: False).
• --myst-url-schemes=<comma-delimited>|<yaml-dict> — URI schemes that are converted to external links (default: http,https,mailto,ftp).
• --myst-fence-as-directive=<comma-delimited> — Interpret a code fence as a directive, for certain language names. This can be useful for fences like dot and mermaid, and interoperability with other Markdown renderers.
• --myst-number-code-blocks=<comma-delimited> — Add line numbers to code blocks with these languages.
• --myst-title-to-header=<boolean> — Convert a title field in the front-matter to a H1 header (default: False).
• --myst-heading-anchors=<int> — Heading level depth to assign HTML anchors (default: 0).
• --myst-heading-slug-func=<str> — Function for creating heading anchors, or a python import path e.g. my_package.my_module.my_function (default: (default: 'None')).
• --myst-html-meta=<yaml-dict> — HTML meta tags.
• --myst-footnote-sort=<boolean> — Move all footnotes to the end of the document, and sort by reference order (default: True).
• --myst-footnote-transition=<boolean> — Place a transition before sorted footnotes (default: True).
• --myst-words-per-minute=<int> — For reading speed calculations (default: 200).
• --myst-substitutions=<yaml-dict> — Substitutions mapping.
• --myst-linkify-fuzzy-links=<boolean> — Recognise URLs without schema prefixes (default: True).
• --myst-dmath-allow-labels=<boolean> — Parse $$...$$ (label) (default: True).
• --myst-dmath-allow-space=<boolean> — Allow initial/final spaces in $ ... $ (default: True).
• --myst-dmath-allow-digits=<boolean> — Allow initial/final digits 1$ ...$2 (default: True).
• --myst-dmath-double-inline=<boolean> — Parse inline $$ ... $$ (default: False).
• --myst-enable-checkboxes=<boolean> — Enable checkboxes (default: False).
• --myst-suppress-warnings=<comma-delimited> — A list of warning types to suppress warning messages.
• --myst-highlight-code-blocks=<boolean> — Syntax highlight code blocks with pygments (default: True).
• --myst-inventories=<yaml-dict> — Mapping of key to (url, inv file), for intra-project referencing.

🧩 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 — turns on the directives that literally pull in the contents of an external file. yes bestie, file go in. this is the default btw 💖
• --no-raw — kills the "raw" directive, and instead of your raw content you get a "warning" system message. rude but fair 🫠
• --raw-enabled — the "raw" directive is on. (default) raw dogging your markup, iconic
• --line-length-limit=<length> — the max number of characters in one input line. default is 10 000. that's a LOT of line, she's long 💅
• --validate — validates the document tree after parsing. proofread era ✨
• --no-validation — don't validate the document tree. (default) we die like women 😭

---

🌸 reStructuredText Parser Options 🌸

• --pep-references — recognizes standalone PEP references (like "PEP 258") and links them up. PEP girlies rise 🫶
• --pep-base-url=<URL> — the base URL for those PEP references. (default: "https://peps.python.org/")
• --pep-file-url-template=<URL> — the template for the PEP file part of the URL. (default: "pep-%04d") yes the %04d is doing the heavy lifting, don't touch it 💀
• --rfc-references — recognizes standalone RFC references (like "RFC 822") and links them too. old-school internet slay 🎀
• --rfc-base-url=<URL> — base URL for RFC references. (default: "https://tools.ietf.org/html/")
• --tab-width=<width> — how many spaces a tab expands to. (default 8)
• --trim-footnote-reference-space — removes the spaces before footnote references. decluttered, clean, minimal 🧚
• --leave-footnote-reference-space — leaves the spaces before footnote references alone. she's keeping them, respect it
• --syntax-highlight=<format> — the token name set used when parsing code with Pygments. one of "long", "short", or "none" (no parsing). default is "long".
• --smart-quotes=<yes/no/alt> — swaps your straight quotation marks for typographic ones. one of "yes", "no", "alt[ernative]". (default: "no") — so by default your quotes stay basic, but you CAN make them fancy ✨
• --smartquotes-locales=<language:quotes[,language:quotes,...]> — which characters count as "smart quotes" for <language>. localized curly-quote representation, we love to see it 🌈
• --word-level-inline-markup — inline markup is only recognized at word boundaries (so, next to punctuation or whitespace). you can force character-level recognition with "\ " (backslash + space). this is the default.
• --character-level-inline-markup — inline markup gets recognized ANYWHERE, no matter what characters are chilling around it. you have to use backslash-escapes to stop unwanted markup from being recognized. useful for East Asian languages. labeled Experimental — so like, cute but proceed with awareness 🫶

---

🦋 Standalone Reader Options 🦋

• --no-doc-title — disables the promotion of a lone top-level section title to document title (and the subsequent promotion of a section title to document subtitle — that whole thing is enabled by default). no promotion for you 📉
• --no-doc-info — disables the bibliographic field list transform (which is enabled by default).
• --section-subtitles — activates the promotion of lone subsection titles to section subtitles (this one's disabled by default).
• --no-section-subtitles — deactivates that lone-subsection-title promotion. back off, subtitle era over

---

💅 HTML Writer Options 💅

• --template=<file> — the template file. UTF-8 encoded, default: "/usr/share/docutils/writers/html5_polyglot/template.txt". long path, big vibes
• --stylesheet=<URL[,URL,...]> — a comma separated list of stylesheet URLs. this one overrides any previous --stylesheet and --stylesheet-path settings. she's the main character, periodt 👑
• --stylesheet-path=<file[,file,...]> — a comma separated list of stylesheet paths. relative paths get expanded if a matching file turns up in the --stylesheet-dirs. with --link-stylesheet, the path is rewritten relative to the output HTML file. (default: "minimal.css,plain.css") two icons in one
• --stylesheet-dirs=<dir[,dir,...]> — comma-separated list of directories where stylesheets live. used by --stylesheet-path when it's expanding those relative path arguments. (default: ".,/usr/share/docutils/writers/html5_polyglot")
• --embed-stylesheet — embeds the stylesheet(s) directly in the output HTML file. the stylesheet files must be accessible during processing. (default) it's giving self-contained 🎀
• --link-stylesheet — links to the stylesheet(s) in the output HTML file instead. external reference realness
• --initial-header-level=<level> — sets the initial header level. note: it does not affect the document title & subtitle (see --no-doc-title). (default: 2 for "<h2>")
• --footnote-references=<format> — the format for footnote references. one of "superscript" or "brackets". (default: "brackets")
• --attribution=<format> — the format for block quote attributions. one of "dash" (em-dash prefix), "parentheses"/"parens", or "none". (default: "dash")
• --compact-lists — removes the extra vertical whitespace between items of "simple" bullet lists and enumerated lists. (default) tight, tidy, efficient 💖
• --no-compact-lists — disables compact simple bullet and enumerated lists. let them breathe, ig
• --compact-field-lists — removes the extra vertical whitespace between items of simple field lists. (default)
• --no-compact-field-lists — disables compact simple field lists. spacing girlies keep your spacing
• --table-style=<style> — the class value(s) assigned to all tables. the defined styles are: borderless, booktabs, align-left, align-center, alignright, colwidths-auto, colwidths-grid. copy-paste these exactly bestie, no ✨creative✨ renaming
• --math-output=<format [option(s)]> — the math output format (one of "MathML", "HTML", "MathJax", or "LaTeX") plus any option(s). (default: "MathML") math but make it aesthetic 🔥
• --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 in standardscompliant browsers. spam bots stay losing 💀

---

⭐ HTML5 Writer Options ⭐

• --image-loading=<strategy> — suggests at which point images should load: "embed", "link" (default), or "lazy". lazy loading is so her 🌸
• --section-self-link — appends a self-link to section headings. every section linking to itself, self-love era 🫶
• --no-section-self-link — does not append a self-link to section headings. (default) no self-links, humble queen

---

obvi reminder: everything in here is exactly as the page says it — no invented behaviour, no guessing at defaults. if it's not in the list, it's not a vibe 😤

okay that's the whole thing bestie, we ATE 💅✨ this page is from the debian source, January 2026 edition — you're welcome, go build something iconic 🎀🦋