MYSTNB-DOCUTILS-HTML(1)

NAME
mystnb-docutils-html - mystnb-docutils-html

DESCRIPTION
Usage =====

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

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. 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

Enable directives that insert the contents of an
    external file. (default)

--no-raw Disable the "raw" directive; replaced with a "warning"

    system message.

--raw-enabled Enable the "raw" directive. (default) --line-length-limit=<length>

Maximal number of characters in an input line. Default
    10 000.

--validate Validate the document tree after parsing. --no-validation Do not validate the document tree. (default)

reStructuredText Parser Options ------------------------------- --pep-references 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>

Template for PEP file part of 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> Set number of spaces for tab expansion (default 8). --trim-footnote-reference-space

    Remove spaces before footnote references.

--leave-footnote-reference-space

    Leave spaces before footnote references.

--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>

Change straight quotation marks to typographic form:
    one of "yes", "no", "alt[ernative]" (default "no").

--smartquotes-locales=<language:quotes[,language:quotes,...]>

    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 "\ " (backslash + space). 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 Disable the promotion of a lone top-level section

title to document title (and subsequent section title
    to document subtitle promotion; enabled by default).

--no-doc-info Disable the bibliographic field list transform

    (enabled by default).

--section-subtitles Activate the promotion of lone subsection titles to

    section subtitles (disabled by default).

--no-section-subtitles Deactivate the promotion of lone subsection titles.

HTML Writer Options ------------------- --template=<file> Template file. (UTF-8 encoded, default:

    "/usr/share/docutils/writers/html4css1/template.txt")

--stylesheet=<URL[,URL,...]>

Comma separated list of stylesheet URLs. Overrides
    previous --stylesheet and --stylesheet-path settings.

--stylesheet-path=<file[,file,...]>

Comma separated list of stylesheet paths. Relative
    paths are 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: "html4css1.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/docut ils/writers/html4css1,/usr/share/docutils/writers/html 5_polyglot")

--embed-stylesheet Embed the stylesheet(s) in the output HTML file. The

stylesheet files must be accessible during processing.
    (default)

--link-stylesheet Link 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: 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"

(em-dash prefix), "parentheses"/"parens", or "none".
    (default: "dash")

--compact-lists Remove extra vertical whitespace between items of

    "simple" bullet lists and enumerated lists. (default)

--no-compact-lists Disable compact simple bullet and enumerated lists. --compact-field-lists Remove extra vertical whitespace between items of

    simple field lists. (default)

--no-compact-field-lists

    Disable compact simple field lists.

  --table-style=<style> Class value(s) assigned to all tables. Defined styles:

    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") and option(s). (default: "HTML math.css")

--xml-declaration Prepend an XML declaration (default). --no-xml-declaration Omit the XML declaration. --cloak-email-addresses

Obfuscate email addresses to confuse harvesters while
    still keeping email links usable with standardscompliant browsers.

HTML4 Writer Options -------------------- --field-name-limit=<level>

Specify the maximum width (in characters) for onecolumn field names.
    Longer field names will span an

entire row of the table used to render the field list.
    Default is 14 characters. Use 0 for "no limit".

--option-limit=<level> Specify 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. Use 0 for "no limit".