CLI reference

Open in

Name

carta - Document converter

Synopsis

carta [-f|--from] [-t|--to] [-o|--output] [--extract-media] [--resource-path] [--embed-resources] [--self-contained] [--sandbox] [-s|--standalone] [--template] [-V|--variable] [--wrap] [--columns] [-N|--number-sections] [--toc] [--toc-depth] [--mathjax] [--katex] [-M|--metadata] [--metadata-file] [-F|--filter] [--data-dir] [-c|--css] [--epub-cover-image] [--epub-embed-font] [--epub-metadata] [--epub-subdirectory] [--split-level] [--reference-doc] [--highlight-style] [--no-highlight] [--syntax-highlighting] [--syntax-definition] [--list-highlight-languages] [--list-highlight-styles] [--print-highlight-style] [--list-input-formats] [--list-output-formats] [--list-extensions] [-D|--print-default-template] [--version] [-h|--help] [INPUT]

Description

Document converter

Options

-f, --from <FROM>
Input format (e.g. commonmark, json)

-t, --to <TO>
Output format (e.g. html, json)

-o, --output <OUTPUT>
Write output to this file instead of stdout

--extract-media <DIR>
Extract the input's embedded media to this directory, writing each resource as a file and rewriting the document's references to point at the extracted files

--resource-path <SEARCHPATH>
Search these directories, in order, for a document's images and other resources before falling back to the working directory, when a container format embeds them. Directories are separated by the platform's path separator (: on Unix, ; on Windows); repeatable

--embed-resources
Inline a document's referenced media into HTML output as data: URIs, producing a self-contained file with no external resource dependencies. Local resources are read from disk (honoring --resource-path); references that cannot be read are left as written. Ignored for non-HTML output

--self-contained
Deprecated alias for --embed-resources --standalone: produce a self-contained standalone HTML file

--sandbox
Disable network access: remote (http(s)://) resources referenced by the document are not fetched. References that would be embedded are left external and a warning is emitted. Use when converting untrusted documents to avoid fetching document-controlled URLs

-s, --standalone
Produce a standalone document, wrapping the body in the format's template

--template <FILE>
Render with this template file instead of the format's built-in default; implies -s

-V, --variable <KEY[:VAL]>
Set a template variable: KEY:VAL (or KEY=VAL), or bare KEY for true. Repeatable; a repeated key accumulates into a list

--wrap <auto|none|preserve> [default: auto]
Text wrapping in the output: auto reflows to the column width, none keeps each block on a single line, preserve keeps the input's own line breaks

--columns <N>
Column at which --wrap=auto reflows text. Defaults to the writer's built-in width

-N, --number-sections
Number section headings (1, 1.1, …)

--toc
Include an automatically generated table of contents in the standalone output

--toc-depth <N>
The deepest heading level the table of contents includes (default 3; 1–6)

--mathjax[=<URL>]
Use MathJax to display embedded TeX math in HTML output. An optional URL overrides the script location

--katex[=<URL>]
Use KaTeX to display embedded TeX math in HTML output. An optional URL overrides the asset base location

-M, --metadata <KEY[:VAL]>
Set a metadata field: KEY:VAL (or KEY=VAL; true/false become booleans), or bare KEY for true. Repeatable

--metadata-file <FILE>
Read metadata from a YAML or JSON file. Repeatable; later files override earlier ones, and all sit below the document's own metadata

-F, --filter <PROGRAM>
Transform the document through this JSON filter before writing: a program that reads the document as JSON on stdin, receives the output format name as its argument, and writes the transformed JSON on stdout. Repeatable; filters run in the order given

--data-dir <DIR>
Search this directory for user data (filters in filters/, templates in templates/, syntax definitions in syntax/) before the built-in locations. Defaults to $XDG_DATA_HOME/carta (or ~/.local/share/carta)

-c, --css <FILE>
Style an EPUB with this stylesheet, embedded in the book and linked from every page in place of the built-in one. Repeatable; several sheets are linked in order

--epub-cover-image <FILE>
Use this image as an EPUB's cover, generating a dedicated cover page

--epub-embed-font <FILE>
Embed this font file in an EPUB. Repeatable

--epub-metadata <FILE>
Merge Dublin Core metadata from this XML file into an EPUB's package document

--epub-subdirectory <DIRNAME>
Hold an EPUB's content in this container subdirectory (default EPUB; empty for the archive root)

--split-level <N>
Split the document into separate files at this heading level (EPUB). --epub-chapter-level is an accepted alias

--reference-doc <FILE>
Style a DOCX from this reference document: its styling parts and document template are reused, and the converted content is generated into it

--highlight-style <STYLE|FILE>
Colorize code blocks with this style: a built-in name (--list-highlight-styles) or a JSON theme file. Overrides the style selected by --syntax-highlighting

--no-highlight
Leave code blocks unhighlighted (equivalent to --syntax-highlighting=none)

--syntax-highlighting <none|default|idiomatic|STYLE|FILE>
How code blocks are presented: default colorizes them, none leaves them plain, idiomatic uses the target format's own listing construct, and any other value names a built-in style or a JSON theme file to colorize with

--syntax-definition <FILE>
Load an additional syntax definition (a KDE-syntax XML file) whose language joins the catalog, overriding a built-in of the same name. Repeatable

--list-highlight-languages
List the languages this build can highlight and exit

--list-highlight-styles
List the built-in highlight styles and exit

--print-highlight-style <STYLE|FILE>
Print a highlight style (a built-in name or a theme file) as a JSON theme and exit

--list-input-formats
List the input formats this build supports and exit

--list-output-formats
List the output formats this build supports and exit

--list-extensions[=<FORMAT>]
List extensions and their default state for FORMAT (the Markdown dialect if omitted) and exit

-D, --print-default-template <FORMAT>
Print the built-in default template for FORMAT and exit

--version
Print version information and exit

-h, --help
Print help

[INPUT]
Read input from this file instead of stdin