.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
.TH MYSTNB-DOCUTILS-XML "1" "April 2024" "debian" "User Commands"
.SH NAME
mystnb-docutils-xml \- mystnb-docutils-xml
.SH DESCRIPTION
Usage
=====
.IP
mystnb\-docutils\-xml [options] [<source> [<destination>]]
.PP
Generates Docutils\-native XML 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\-outputfolder`.
.PP
Options
=======
General Docutils Options
\fB\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\fR
\fB\-\-output=\fR<destination>  Output destination name. Obsoletes the <destination>
.IP
positional argument. Default: None (stdout).
.PP
\fB\-\-title=\fR<title>         Specify the document title as metadata.
\fB\-\-generator\fR, \fB\-g\fR         Include a "Generated by Docutils" credit and link.
\fB\-\-no\-generator\fR          Do not include a generator credit.
\fB\-\-date\fR, \fB\-d\fR              Include the date at the end of the document (UTC).
\fB\-\-time\fR, \fB\-t\fR              Include the time & date (UTC).
\fB\-\-no\-datestamp\fR          Do not include a datestamp of any kind.
\fB\-\-source\-link\fR, \fB\-s\fR       Include a "View document source" link.
\fB\-\-source\-url=\fR<URL>      Use <URL> for a source link; implies \fB\-\-source\-link\fR.
\fB\-\-no\-source\-link\fR        Do not include a "View document source" link.
\fB\-\-toc\-entry\-backlinks\fR   Link from section headers to TOC entries.  (default)
\fB\-\-toc\-top\-backlinks\fR     Link from section headers to the top of the TOC.
\fB\-\-no\-toc\-backlinks\fR      Disable backlinks to the table of contents.
\fB\-\-footnote\-backlinks\fR    Link from footnotes/citations to references. (default)
\fB\-\-no\-footnote\-backlinks\fR
.IP
Disable backlinks from footnotes and citations.
.PP
\fB\-\-section\-numbering\fR     Enable section numbering by Docutils.  (default)
\fB\-\-no\-section\-numbering\fR  Disable section numbering by Docutils.
\fB\-\-strip\-comments\fR        Remove comment elements from the document tree.
\fB\-\-leave\-comments\fR        Leave comment elements in the document tree. (default)
\fB\-\-strip\-elements\-with\-class=\fR<class>
.TP
Remove all elements with classes="<class>" from the
document tree. Warning: potentially dangerous; use
with caution. (Multiple\-use option.)
.PP
\fB\-\-strip\-class=\fR<class>   Remove all classes="<class>" attributes from elements
.TP
in the document tree. Warning: potentially dangerous;
use with caution. (Multiple\-use option.)
.PP
\fB\-\-report=\fR<level>, \fB\-r\fR <level>
.TP
Report system messages at or higher than <level>:
"info" or "1", "warning"/"2" (default), "error"/"3",
"severe"/"4", "none"/"5"
.PP
\fB\-\-verbose\fR, \fB\-v\fR           Report all system messages.  (Same as "\-\-report=1".)
\fB\-\-quiet\fR, \fB\-q\fR             Report no system messages.  (Same as "\-\-report=5".)
\fB\-\-halt=\fR<level>          Halt execution at system messages at or above <level>.
.TP
Levels as in \fB\-\-report\fR.
Default: 4 (severe).
.PP
\fB\-\-strict\fR                Halt at the slightest problem.  Same as "\-\-halt=info".
\fB\-\-exit\-status=\fR<level>   Enable a non\-zero exit status for non\-halting system
.TP
messages at or above <level>.
Default: 5 (disabled).
.PP
\fB\-\-debug\fR                 Enable debug\-level system messages and diagnostics.
\fB\-\-no\-debug\fR              Disable debug output.  (default)
\fB\-\-warnings=\fR<file>       Send the output of system messages to <file>.
\fB\-\-traceback\fR             Enable Python tracebacks when Docutils is halted.
\fB\-\-no\-traceback\fR          Disable Python tracebacks.  (default)
\fB\-\-input\-encoding=\fR<name[:handler]>, \fB\-i\fR <name[:handler]>
.TP
Specify the encoding and optionally the error handler
of input text.  Default: <auto\-detect>:strict.
.PP
\fB\-\-input\-encoding\-error\-handler\fR=\fI\,INPUT_ENCODING_ERROR_HANDLER\/\fR
.TP
Specify the error handler for undecodable characters.
Choices: "strict" (default), "ignore", and "replace".
.PP
\fB\-\-output\-encoding=\fR<name[:handler]>, \fB\-o\fR <name[:handler]>
.TP
Specify the text encoding and optionally the error
handler for output.  Default: utf\-8:strict.
.PP
\fB\-\-output\-encoding\-error\-handler\fR=\fI\,OUTPUT_ENCODING_ERROR_HANDLER\/\fR
.TP
Specify error handler for unencodable output
characters; "strict" (default), "ignore", "replace",
"xmlcharrefreplace", "backslashreplace".
.PP
\fB\-\-error\-encoding=\fR<name[:handler]>, \fB\-e\fR <name[:handler]>
.TP
Specify text encoding and optionally error handler for
error output.  Default text encoding: system encoding.
Default error handler: backslashreplace.
.PP
\fB\-\-error\-encoding\-error\-handler\fR=\fI\,ERROR_ENCODING_ERROR_HANDLER\/\fR
.TP
Specify the error handler for unencodable characters
in error output.  Default: backslashreplace.
.PP
\fB\-\-language=\fR<name>, \fB\-l\fR <name>
.TP
Specify the language (as BCP 47 language tag).
Default: en.
.PP
\fB\-\-record\-dependencies=\fR<file>
.IP
Write output file dependencies to <file>.
.PP
\fB\-\-config=\fR<file>         Read configuration settings from <file>, if it exists.
\fB\-\-version\fR, \fB\-V\fR           Show this program's version number and exit.
\fB\-\-help\fR, \fB\-h\fR              Show this help message and exit.
.PP
MyST\-NB options
\fB\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\fR
\fB\-\-nb\-read\-as\-md=\fR<boolean>
.IP
Read as the MyST Markdown format (default: False)
.PP
\fB\-\-nb\-metadata\-key=\fR<str>
.TP
Notebook level metadata key for config overrides
(default: (default: 'mystnb'))
.PP
\fB\-\-nb\-cell\-metadata\-key=\fR<str>
.TP
Cell level metadata key for config overrides (default:
(default: 'mystnb'))
.PP
\fB\-\-nb\-eval\-name\-regex=\fR<str>
.TP
Regex that matches permitted values of eval
expressions (default: (default: '^[a\-zAZ_][a\-zA\-Z0\-9_]*$'))
.PP
\fB\-\-nb\-execution\-mode=\fR<'off'|'force'|'auto'|'cache'|'inline'>
.IP
Execution mode for notebooks (default: 'auto')
.PP
\fB\-\-nb\-execution\-cache\-path=\fR<str>
.TP
Path to folder for caching notebooks (default:
<outdir>) (default: (default: ''))
.PP
\fB\-\-nb\-execution\-timeout=\fR<int>
.IP
Execution timeout (seconds) (default: 30)
.PP
\fB\-\-nb\-execution\-in\-temp=\fR<boolean>
.TP
Use temporary folder for the execution current working
directory (default: False)
.PP
\fB\-\-nb\-execution\-allow\-errors=\fR<boolean>
.IP
Allow errors during execution (default: False)
.PP
\fB\-\-nb\-execution\-raise\-on\-error=\fR<boolean>
.TP
Raise an exception on failed execution, rather than
emitting a warning (default: False)
.PP
\fB\-\-nb\-execution\-show\-tb=\fR<boolean>
.TP
Print traceback to stderr on execution error (default:
False)
.PP
\fB\-\-nb\-merge\-streams=\fR<boolean>
.TP
Merge stdout/stderr execution output streams (default:
False)
.PP
\fB\-\-nb\-render\-plugin=\fR<str>
.TP
The entry point for the execution output render class
(in group `myst_nb.output_renderer`) (default:
(default: 'default'))
.PP
\fB\-\-nb\-remove\-code\-source=\fR<boolean>
.IP
Remove code cell source (default: False)
.PP
\fB\-\-nb\-remove\-code\-outputs=\fR<boolean>
.IP
Remove code cell outputs (default: False)
.PP
\fB\-\-nb\-code\-prompt\-show=\fR<str>
.TP
Prompt to expand hidden code cell
{content|source|outputs} (default: (default: 'Show
code cell {type}'))
.PP
\fB\-\-nb\-code\-prompt\-hide=\fR<str>
.TP
Prompt to collapse hidden code cell
{content|source|outputs} (default: (default: 'Hide
code cell {type}'))
.PP
\fB\-\-nb\-number\-source\-lines=\fR<boolean>
.IP
Number code cell source lines (default: False)
.PP
\fB\-\-nb\-builder\-name=\fR<str>
.TP
Builder name, to select render priority for mime types
(default: (default: 'html'))
.PP
\fB\-\-nb\-output\-stderr=\fR<'show'|'remove'|'remove\-warn'|'warn'|'error'|'severe'>
.IP
Behaviour for stderr output (default: 'show')
.PP
\fB\-\-nb\-render\-text\-lexer=\fR<str>
.TP
Pygments lexer applied to stdout/stderr and text/plain
outputs (default: (default: 'myst\-ansi'))
.PP
\fB\-\-nb\-render\-error\-lexer=\fR<str>
.TP
Pygments lexer applied to error/traceback outputs
(default: (default: 'ipythontb'))
.PP
\fB\-\-nb\-render\-markdown\-format=\fR<'commonmark'|'gfm'|'myst'>
.TP
The format to use for text/markdown rendering
(default: 'commonmark')
.PP
\fB\-\-nb\-output\-folder=\fR<str>
.TP
Folder for external outputs (like images), skipped if
empty (default: (default: 'build'))
.PP
\fB\-\-nb\-append\-css=\fR<boolean>
.TP
Add default MyST\-NB CSS to HTML outputs (default:
True)
.PP
\fB\-\-nb\-metadata\-to\-fm=\fR<boolean>
.TP
Convert unhandled metadata to frontmatter (default:
False)
.PP
MyST options
\fB\-\-\-\-\-\-\-\-\-\-\-\-\fR
\fB\-\-myst\-commonmark\-only=\fR<boolean>
.IP
Use strict CommonMark parser (default: False)
.PP
\fB\-\-myst\-gfm\-only=\fR<boolean>
.TP
Use strict Github Flavoured Markdown parser (default:
False)
.PP
\fB\-\-myst\-enable\-extensions=\fR<comma\-delimited>
.IP
Enable syntax extensions
.PP
\fB\-\-myst\-disable\-syntax=\fR<comma\-delimited>
.IP
Disable Commonmark syntax elements
.PP
\fB\-\-myst\-all\-links\-external=\fR<boolean>
.IP
Parse all links as simple hyperlinks (default: False)
.PP
\fB\-\-myst\-links\-external\-new\-tab=\fR<boolean>
.IP
Open all external links in a new tab (default: False)
.PP
\fB\-\-myst\-url\-schemes=\fR<comma\-delimited>|<yaml\-dict>
.TP
URI schemes that are converted to external links
(default: http,https,mailto,ftp)
.PP
\fB\-\-myst\-fence\-as\-directive=\fR<comma\-delimited>
.TP
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.
.PP
\fB\-\-myst\-number\-code\-blocks=\fR<comma\-delimited>
.IP
Add line numbers to code blocks with these languages
.PP
\fB\-\-myst\-title\-to\-header=\fR<boolean>
.TP
Convert a `title` field in the front\-matter to a H1
header (default: False)
.PP
\fB\-\-myst\-heading\-anchors=\fR<int>
.TP
Heading level depth to assign HTML anchors (default:
0)
.PP
\fB\-\-myst\-heading\-slug\-func=\fR<str>
.TP
Function for creating heading anchors, or a python
import path e.g. `my_package.my_module.my_function`
(default: (default: 'None'))
.PP
\fB\-\-myst\-html\-meta=\fR<yaml\-dict>
.IP
HTML meta tags
.PP
\fB\-\-myst\-footnote\-transition=\fR<boolean>
.TP
Place a transition before any footnotes (default:
True)
.PP
\fB\-\-myst\-words\-per\-minute=\fR<int>
.IP
For reading speed calculations (default: 200)
.PP
\fB\-\-myst\-substitutions=\fR<yaml\-dict>
.IP
Substitutions mapping
.PP
\fB\-\-myst\-linkify\-fuzzy\-links=\fR<boolean>
.IP
Recognise URLs without schema prefixes (default: True)
.PP
\fB\-\-myst\-dmath\-allow\-labels=\fR<boolean>
.IP
Parse `$$...$$ (label)` (default: True)
.PP
\fB\-\-myst\-dmath\-allow\-space=\fR<boolean>
.TP
Allow initial/final spaces in `$ ... $` (default:
True)
.PP
\fB\-\-myst\-dmath\-allow\-digits=\fR<boolean>
.IP
Allow initial/final digits `1$ ...$2` (default: True)
.PP
\fB\-\-myst\-dmath\-double\-inline=\fR<boolean>
.IP
Parse inline `$$ ... $$` (default: False)
.PP
\fB\-\-myst\-enable\-checkboxes=\fR<boolean>
.IP
Enable checkboxes (default: False)
.PP
\fB\-\-myst\-suppress\-warnings=\fR<comma\-delimited>
.IP
A list of warning types to suppress warning messages
.PP
\fB\-\-myst\-highlight\-code\-blocks=\fR<boolean>
.TP
Syntax highlight code blocks with pygments (default:
True)
.PP
\fB\-\-myst\-inventories=\fR<yaml\-dict>
.TP
Mapping of key to (url, inv file), for intra\-project
referencing
.PP
Generic Parser Options
\fB\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\fR
\fB\-\-no\-file\-insertion\fR     Disable directives that insert the contents of an
.TP
external file; replaced with a "warning" system
message.
.PP
\fB\-\-file\-insertion\-enabled\fR
.TP
Enable directives that insert the contents of an
external file. (default)
.PP
\fB\-\-no\-raw\fR                Disable the "raw" directive; replaced with a "warning"
.IP
system message.
.PP
\fB\-\-raw\-enabled\fR           Enable the "raw" directive. (default)
\fB\-\-line\-length\-limit=\fR<length>
.TP
Maximal number of characters in an input line. Default
10 000.
.PP
reStructuredText Parser Options
\fB\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\fR
\fB\-\-pep\-references\fR        Recognize and link to standalone PEP references (like
.IP
"PEP 258").
.PP
\fB\-\-pep\-base\-url=\fR<URL>    Base URL for PEP references (default
.IP
"https://peps.python.org/").
.PP
\fB\-\-pep\-file\-url\-template=\fR<URL>
.TP
Template for PEP file part of URL. (default
"pep\-%04d")
.PP
\fB\-\-rfc\-references\fR        Recognize and link to standalone RFC references (like
.IP
"RFC 822").
.PP
\fB\-\-rfc\-base\-url=\fR<URL>    Base URL for RFC references (default
.IP
"https://tools.ietf.org/html/").
.PP
\fB\-\-tab\-width=\fR<width>     Set number of spaces for tab expansion (default 8).
\fB\-\-trim\-footnote\-reference\-space\fR
.IP
Remove spaces before footnote references.
.PP
\fB\-\-leave\-footnote\-reference\-space\fR
.IP
Leave spaces before footnote references.
.PP
\fB\-\-syntax\-highlight=\fR<format>
.TP
Token name set for parsing code with Pygments: one of
"long", "short", or "none" (no parsing). Default is
"long".
.PP
\fB\-\-smart\-quotes=\fR<yes/no/alt>
.TP
Change straight quotation marks to typographic form:
one of "yes", "no", "alt[ernative]" (default "no").
.PP
\fB\-\-smartquotes\-locales=\fR<language:quotes[,language:quotes,...]>
.IP
Characters to use as "smart quotes" for <language>.
.PP
\fB\-\-word\-level\-inline\-markup\fR
.TP
Inline markup recognized at word boundaries only
(adjacent to punctuation or whitespace). Force
character\-level inline markup recognition with "\e "
(backslash + space). Default.
.PP
\fB\-\-character\-level\-inline\-markup\fR
.TP
Inline markup recognized anywhere, regardless of
surrounding characters. Backslash\-escapes must be used
to avoid unwanted markup recognition. Useful for East
Asian languages. Experimental.
.PP
Standalone Reader Options
\fB\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\fR
\fB\-\-no\-doc\-title\fR          Disable the promotion of a lone top\-level section
.TP
title to document title (and subsequent section title
to document subtitle promotion; enabled by default).
.PP
\fB\-\-no\-doc\-info\fR           Disable the bibliographic field list transform
.IP
(enabled by default).
.PP
\fB\-\-section\-subtitles\fR     Activate the promotion of lone subsection titles to
.IP
section subtitles (disabled by default).
.PP
\fB\-\-no\-section\-subtitles\fR  Deactivate the promotion of lone subsection titles.
.PP
"Docutils XML" Writer Options
\fB\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\fR
\fB\-\-newlines\fR              Generate XML with newlines before and after tags.
\fB\-\-indents\fR               Generate XML with indents and newlines.
\fB\-\-no\-xml\-declaration\fR    Omit the XML declaration.  Use with caution.
\fB\-\-no\-doctype\fR            Omit the DOCTYPE declaration.