CM2HTML(1)

📦
version 0.7.1 · 4 versions
, in debian bookworm, ubuntu noble

💖 NAME 💖

cm2html — okay so bestie, this little icon converts a CommonMark file into an HTML document. That's it, that's the whole job, and it does it flawlessly. Periodt.

✨ SYNOPSIS ✨

cm2html [options] [<source> [<destination>]]

🌸 DESCRIPTION 🌸

It generates an HTML document from markdown sources, no cap. It reads from <source> — and if you don't give it one, default is stdin 🫶 — and it writes to <destination>, and if you don't give it one, default is stdout. Chef's kiss, honestly.

Want the full settings reference? It lives at https://docutils.sourceforge.io/docs/user/config.html — go be nosy, iykyk. 📖✨

💅 OPTIONS 💅

👑 General Docutils Options

  • --title=TITLE — sets the document title as metadata. Name it, queen.
  • --generator, -g — includes a "Generated by Docutils" credit and link, so everyone knows who did it.
  • --no-generator — does NOT include a generator credit. Humble era.
  • --date, -d — drops the date at the end of the document (UTC).
  • --time, -t — drops the time & date (UTC).
  • --no-datestamp — no datestamp of any kind. Timeless.
  • --source-link, -s — includes a "View document source" link.
  • --source-url=<URL> — uses <URL> for a source link; it also implies --source-link.
  • --no-source-link — no "View document source" link. Sorry to that link.
  • --toc-entry-backlinks — links from section headers back to TOC entries. (default)
  • --toc-top-backlinks — links from section headers to the top of the TOC.
  • --no-toc-backlinks — disables backlinks to the table of contents.
  • --footnote-backlinks — links from footnotes/citations to references. (default)
  • --no-footnote-backlinks — disables backlinks from footnotes and citations.
  • --section-numbering — enables section numbering by Docutils. (default)
  • --no-section-numbering — disables section numbering by Docutils.
  • --strip-comments — removes comment elements from the document tree.
  • --leave-comments — leaves comment elements in the document tree. (default)
  • --strip-elements-with-class=<class> — removes all elements with classes="<class>" from the document tree. > ⚠️ Warning: potentially dangerous; use with caution. (Multiple-use option.)
  • --strip-class=<class> — removes all classes="<class>" attributes from elements in the document tree. > ⚠️ Warning: potentially dangerous; use with caution. (Multiple-use option.)
  • --report=<level>, -r <level> — reports system messages at or higher than <level>: "info" or "1", "warning"/"2" (default), "error"/"3", "severe"/"4", "none"/"5".
  • --verbose, -v — reports all system messages. (Same as "--report=1".)
  • --quiet, -q — reports no system messages. (Same as "--report=5".)
  • --halt=<level> — halts execution at system messages at or above <level>. Levels as in --report. Default: 4 (severe).
  • --strict — halts at the slightest problem. Same as "--halt=info".
  • --exit-status=<level> — enables a non-zero exit status for non-halting system messages at or above <level>. Default: 5 (disabled).
  • --debug — enables debug-level system messages and diagnostics.
  • --no-debug — disables debug output. (default)
  • --warnings=<file> — sends the output of system messages to <file>.
  • --traceback — enables Python tracebacks when Docutils is halted.
  • --no-traceback — disables Python tracebacks. (default)
  • --input-encoding=<name[:handler]>, -i <name[:handler]> — specifies the encoding and optionally the error handler of input text. Default: <auto-detect>:strict.
  • --input-encoding-error-handler=INPUT_ENCODING_ERROR_HANDLER — specifies the error handler for undecodable characters. Choices: "strict" (default), "ignore", and "replace".
  • --output-encoding=<name[:handler]>, -o <name[:handler]> — specifies the text encoding and optionally the error handler for output. Default: utf-8:strict.
  • --output-encoding-error-handler=OUTPUT_ENCODING_ERROR_HANDLER — specifies error handler for unencodable output characters; "strict" (default), "ignore", "replace", "xmlcharrefreplace", "backslashreplace".
  • --error-encoding=<name[:handler]>, -e <name[:handler]> — specifies text encoding and optionally error handler for error output. Default text encoding: system encoding. Default error handler: backslashreplace.
  • --error-encoding-error-handler=ERROR_ENCODING_ERROR_HANDLER — specifies the error handler for unencodable characters in error output. Default: backslashreplace.
  • --language=<name>, -l <name> — specifies the language (as BCP 47 language tag). Default: en.
  • --record-dependencies=<file> — writes output file dependencies to <file>.
  • --config=<file> — reads configuration settings from <file>, if it exists.
  • --version, -V — shows this program's version number and exits. Bye bestie 👋
  • --help, -h — shows this help message and exits.

🧚 Generic Parser Options

  • --no-file-insertion — disables directives that insert the contents of an external file; gets replaced with a "warning" system message.
  • --file-insertion-enabled — enables directives that insert the contents of an external file. (default)
  • --no-raw — disables the "raw" directive; replaced with a "warning" system message.
  • --raw-enabled — enables the "raw" directive. (default)
  • --line-length-limit=<length> — maximal number of characters in an input line. Default 10 000.

🦋 Standalone Reader Options

  • --no-doc-title — disables the promotion of a lone top-level section title to document title (and the subsequent section title to document subtitle promotion; enabled by default).
  • --no-doc-info — disables the bibliographic field list transform (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> — 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/docutils/writers/html4css1,/usr/share/docutils/writers/html5_polyglot")
  • --embed-stylesheet — embeds the stylesheet(s) in the output HTML file. The stylesheet files must be accessible during processing. (default)
  • --link-stylesheet — links to the stylesheet(s) in the output HTML file.
  • --initial-header-level=<level> — specifies 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 — removes 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 extra vertical whitespace between items of simple field lists. (default)
  • --no-compact-field-lists — disables compact simple field lists.
  • --table-style=TABLE_STYLE — added to standard table classes. Defined styles: borderless, booktabs, align-left, align-center, alignright, colwidths-auto, colwidths-grid.
  • --math-output=MATH_OUTPUT — math output format (one of "MathML", "HTML", "MathJax", or "LaTeX") and option(s). (default: "HTML math.css")
  • --xml-declaration — prepends an XML declaration (default).
  • --no-xml-declaration — omits the XML declaration.
  • --cloak-email-addresses — obfuscates email addresses to confuse harvesters while still keeping email links usable with standardscompliant browsers. 🕵️‍♀️

🎀 HTML4 Writer Options

  • --field-name-limit=<level> — specifies 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> — specifies 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".

🫶 AUTHOR 🫶

Steve Genoud and Luca Barbato. Legends, fr fr. 💜

Copyright (C) 2014 Steve Genoud and Luca Barbato.

and that's the whole page, bestie ✨ This one ships as part of the recommonmark Python package, specifically Debian 0.7.1+ds-5, dated February 2023 — so go forth, convert your CommonMark, and slay. 💖🎀🦋

📦 where this page comes from