MYSTNB-DOCUTILS-XML(1)

📦
version 1.3.0 · 6 versions
, in ubuntu resolute, ubuntu stonking

🎀 NAME

okay bestie, this is the MYSTNB-DOCUTILS-XML(1) manual page — User Commands energy — and the main character is literally mystnb-docutils-xml.

mystnb-docutils-xml — mystnb-docutils-xml

💖 DESCRIPTION

🌸 Usage

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

It generates Docutils-native XML from standalone MyST Notebook sources. Reads from <source> (default is stdin) and writes to <destination> (default is stdout). For the detailed settings reference, see https://docutils.sourceforge.io/docs/user/config.html. External outputs are written to --nb-outputfolder.

✨ Yes, that is --nb-outputfolder exactly as written here. Do not come for me; I am just relaying the lore.

🛠️ 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 pull in the contents of an external file. This is the default, bestie — it's already on. ✨
  • --no-raw — disables the "raw" directive, and it gets swapped out for a "warning" system message instead. RIP raw, you had a good run.
  • --raw-enabled — enables the "raw" directive again. Also the default, so yeah, it's on unless you said otherwise.
  • --line-length-limit=<length> — the max number of characters allowed in a single input line. Default is 10 000. Ten thousand. That's the ceiling. Don't test it. 😭
  • --validate — validates the document tree after parsing. Quality control era.
  • --no-validation — doesn't validate the document tree. This is the default, so no vibes are being checked unless you ask.

🌸 reStructuredText Parser Options 🌸

  • --pep-references — recognizes standalone PEP references and links them up (like "PEP 258"). iykyk 💅
  • --pep-base-url=<URL> — the base URL used for PEP references. Default is "https://peps.python.org/".
  • --pep-file-url-template=<URL> — the template for the PEP file part of the URL. Default is "pep-%04d". yes, that's a format specifier, she's fancy like that.
  • --rfc-references — recognizes standalone RFC references and links them (like "RFC 822"). the OGs of the spec world fr fr
  • --rfc-base-url=<URL> — the base URL for RFC references. Default is "https://tools.ietf.org/html/".
  • --tab-width=<width> — sets the number of spaces used for tab expansion. Default is 8. tabs → spaces, the eternal discourse 🫶
  • --trim-footnote-reference-space — removes spaces before footnote references. snip snip ✂️
  • --leave-footnote-reference-space — leaves the spaces before footnote references alone. she's chill, she's not touching them.
  • --syntax-highlight=<format> — the token name set used for parsing code with Pygments: one of "long", "short", or "none" (which means no parsing at all). Default is "long". Pygments girlies rise 🔥
  • --smart-quotes=<yes/no/alt> — changes straight quotation marks into typographic form: one of "yes", "no", "alt[ernative]". Default is "no". the curly quotes glow-up ✨
  • --smartquotes-locales=<language:quotes[,language:quotes,...]> — the characters to use as "smart quotes" for <language>. localized curly quotes, we love to see it 🌈
  • --word-level-inline-markup — inline markup is only recognized at word boundaries (aka adjacent to punctuation or whitespace). You can force character-level inline markup recognition with "\ " (backslash + space). This one's the default.
  • --character-level-inline-markup — inline markup is recognized anywhere, no matter what characters are around it. You must use backslash-escapes to avoid unwanted markup recognition. Useful for East Asian languages. Experimental, bestie — tread carefully. 💀

🎀 Standalone Reader Options 🎀

  • --no-doc-title — disables the promotion of a lone top-level section title to document title (and the subsequent section title → document subtitle promotion; this whole thing is enabled by default). no promotions today, we're keeping the org chart flat.
  • --no-doc-info — disables the bibliographic field list transform (which is enabled by default). the bibliography is off duty 💅
  • --section-subtitles — activates the promotion of lone subsection titles to section subtitles. Disabled by default, so you gotta opt in.
  • --no-section-subtitles — deactivates the promotion of lone subsection titles. promotion revoked 👑

👑 "Docutils XML" Writer Options 👑

  • --newlines — generates XML with newlines before and after tags. room to breathe ✨
  • --indents — generates XML with indents and newlines. the full aesthetic treatment 🎀
  • --no-xml-declaration — omits the XML declaration. Use with caution. like, genuinely caution, bestie 😭
  • --no-doctype — omits the DOCTYPE declaration. bye bye doctype 👋
okay that's the whole page, no cap — every flag accounted for, nothing skipped, nothing invented. slay 🦋

And that's a wrap, bestie 💖 huge thanks to the debian fam for shipping this page — dated January 2026 in the MYSTNB-DOCUTILS-XML(1) era of the manual. Go parse something iconic. 🫶

📦 where this page comes from