docspec-cli

Command-line interface for DocSpec document conversion.

See the main DocSpec repository for documentation.

Usage

docspec [OPTIONS] [INPUT]

Arguments

• INPUT — Input file (use - or omit for stdin)

Options

• -o, --output <FILE> — Output file (stdout if omitted)
• -f, --from <FORMAT> — Input format (auto-detected from extension if omitted). Valid values: markdown, html
• -t, --to <FORMAT> — Output format (auto-detected from extension if omitted). Valid values: blocknote, html, oxa
• --color <WHEN> — When to use colors: auto, always, never (default: auto)
• -h, --help — Print help
• -V, --version — Print version

Supported Input Formats

• markdown — Full Markdown support including headings, lists, tables, and inline formatting
• html — HTML input (see note below)

Note: HTML input and output currently preserve only paragraph text. Other HTML input elements and non-paragraph output events (headings, lists, tables, formatting tags, etc.) are silently dropped. For fuller feature coverage, use Markdown input with BlockNote JSON output.

Examples

Convert a Markdown file to BlockNote JSON:

docspec --from markdown --to blocknote input.md --output output.json

Convert an HTML file to BlockNote JSON (paragraphs only):

docspec --from html --to blocknote input.html --output output.json

Convert Markdown from stdin to BlockNote JSON on stdout:

echo "# Hello" | docspec --from markdown --to blocknote

Convert Markdown to HTML:

echo "Hello" | docspec --from markdown --to html

--to oxa selects the oxa.dev JSON writer in place of BlockNote. The .json extension is ambiguous, so --to oxa must be explicit. HTML output is selected by --to html or auto-detected from .html and .htm output paths.