MYSTNB-DOCUTILS-HTML(1)

💅 MYSTNB-DOCUTILS-HTML(1) 💅

okay so this is the User Commands manual page for mystnb-docutils-html — yes, the page is literally titled MYSTNB-DOCUTILS-HTML(1), and the command is literally mystnb-docutils-html. bestie, we're going in. 💖

🎀 NAME 🎀

• mystnb-docutils-html — that's the command. That's the name. iconic. ✨

🌸 DESCRIPTION 🌸

🫶 Usage 🫶

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

It generates (X)HTML documents from standalone MyST Notebook sources. 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. External outputs are written to --nb-output-folder. 🫶

✨ Options ✨

💖 General Docutils Options 💖

• --output-path=<destination>, --output=<destination> — output destination name. It 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; page says (default: (default: 'mystnb')).
• --nb-cell-metadata-key=<str> — cell level metadata key for config overrides; page says (default: (default: 'mystnb')).
• --nb-eval-name-regex=<str> — regex that matches permitted values of eval expressions; page says (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; page says (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); page says (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}; page says (default: (default: 'Show code cell {type}')).
• --nb-code-prompt-hide=<str> — prompt to collapse hidden code cell {content|source|outputs}; page says (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; page says (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; page says (default: (default: 'myst-ansi')).
• --nb-render-error-lexer=<str> — Pygments lexer applied to error/traceback outputs; page says (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; page says (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; page says (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 those directives that pull in the contents of an external file. yep, that's the default 💖
• --no-raw — disables the raw directive entirely, and instead of it doing its thing you get a warning system message instead 🫶
• --raw-enabled — enables the raw directive. (this is the default, bestie)
• --line-length-limit=<length> — the max number of characters allowed in a single input line. Default is 10 000 👑
• --validate — validate the document tree after parsing.
• --no-validation — don't validate the document tree. (default, so if you skip this whole argument you're in no-validation land 🦋)

---

✨ reStructuredText Parser Options ✨

• --pep-references — makes it 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> — the 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> — how many spaces a tab expands to. Default is 8.
• --trim-footnote-reference-space — remove the spaces before footnote references.
• --leave-footnote-reference-space — leave the spaces before footnote references alone 🎀
• --syntax-highlight=<format> — the token name set used for parsing code with Pygments. it's one of "long", "short", or "none" (and "none" means no parsing at all, obviously). default is "long".
• --smart-quotes=<yes/no/alt> — swaps straight quotation marks for the typographic form. one of "yes", "no", "alt[ernative]". default is "no" ⭐
• --smartquotes-locales=<language:quotes[,language:quotes,...]> — which characters get used as "smart quotes" for <language>.
• --word-level-inline-markup — inline markup only gets recognized at word boundaries (aka right next to punctuation or whitespace). you can force character-level inline markup recognition with \ (backslash + space). this one is the default 🧚
• --character-level-inline-markup — inline markup gets recognized anywhere, no matter what characters are around it. you must use backslash-escapes to avoid unwanted markup recognition here. it's useful for East Asian languages. also: it's Experimental, so like, heads up 💀

---

✨ Standalone Reader Options ✨

• --no-doc-title — disables the promotion of a lone top-level section title into a document title (and the subsequent section title → document subtitle promotion too; that whole thing is enabled by default).
• --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 (disabled by default).
• --no-section-subtitles — deactivates the promotion of lone subsection titles 🦋

---

✨ HTML Writer Options ✨

• --template=<file> — the template file. it's UTF-8 encoded, and the default is "/usr/share/docutils/writers/html4css1/template.txt"
• --stylesheet=<URL[,URL,...]> — comma separated list of stylesheet URLs. this one overrides any previous --stylesheet and --stylesheet-path settings, so it fully eats 💅
• --stylesheet-path=<file[,file,...]> — comma separated list of stylesheet paths. relative paths get expanded if a matching file turns up in the --stylesheet-dirs. and with --link-stylesheet, the path gets rewritten relative to the output HTML file. (default: "html4css1.css")
• --stylesheet-dirs=<dir[,dir,...]> — comma-separated list of directories where stylesheets live. it's used by --stylesheet-path when expanding those relative path arguments. (default: ".,/usr/share/docutils/writers/html4css1,/usr/share/docutils/writers/html5_polyglot") 🌈
• --embed-stylesheet — embeds the stylesheet(s) straight into the output HTML file. the stylesheet files have to be accessible during processing for this to work. (default)
• --link-stylesheet — links to the stylesheet(s) in the output HTML file instead.
• --initial-header-level=<level> — sets the initial header level. this does not touch the document title & subtitle (go look at --no-doc-title for those). (default: 1 for "<h1>")
• --footnote-references=<format> — format for footnote references: one of "superscript" or "brackets". (default: "brackets") 🎀
• --attribution=<format> — format for block quote attributions: one of "dash" (that's an 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)
• --no-compact-lists — disables compact simple bullet and enumerated lists.
• --compact-field-lists — removes the 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. the defined styles are: borderless, booktabs, align-left, align-center, alignright, colwidths-auto, colwidths-grid ✨
• --math-output=<format [option(s)]> — math output format (one of "MathML", "HTML", "MathJax", or "LaTeX") plus option(s). (default: "HTML math.css")
• --xml-declaration — prepend an XML declaration. (default)
• --no-xml-declaration — omit the XML declaration.
• --cloak-email-addresses — obfuscates email addresses to confuse harvesters while still keeping email links usable with standards-compliant browsers. sneaky, iconic, we love her 🙈

---

✨ HTML4 Writer Options ✨

• --field-name-limit=<level> — the maximum width (in characters) for one-column field names. longer field names will span an entire row of the table used to render the field list. default is 14 characters, and 0 means "no limit" 👑
• --option-limit=<level> — the maximum width (in characters) for options in option lists. longer options will span an entire row of the table used to render the option list. default is 14 characters, and 0 means "no limit" 💜

---

and that's the whole page, bestie — no cap, nothing skipped 🫶 this build is the debian one, dated January 2026, and it's filed under MYSTNB-DOCUTILS-HTML(1) in section 1. go forth and slay your HTML conversion 💅✨