Converting Stencila documents

NO_COLOR=1 stencila convert input.docx output.smd --yes

Formats are inferred from file extensions; --from/--to override. The input may be a path, a URL, or a bare identifier (see Ingestion below). stencila formats list prints the live capability table, which formats decode (From), encode (To), and are lossless. Consult it rather than guessing.

Lossless vs lossy

Only the data formats round-trip losslessly: CBOR, CBOR+Zstd, JSON, JSON+Zip, JSON5, JSON-LD, YAML. Everything else, DOCX, PDF, LaTeX, JATS, HTML, Markdown flavours, IPYNB, is lossy to some degree.

When converting to a lossy target, quantify what is dropped:

• --input-losses, action on losses decoding the input
• --output-losses, action on losses encoding the output

Both accept ignore, trace, debug (default), info, warn, error, abort, or a .json/.yaml filename to write the losses to. After a lossy conversion, tell the user what was lost rather than silently producing a smaller document.

Decoding options that matter

• --fine / --coarse, decoding granularity. Fine (the default for most formats) decodes to the finest structure; coarse preserves un-modelled markup in larger blocks and is the default for LaTeX. Use --coarse when fine decoding of a partially supported format mangles structure.
• --pages N-M / --exclude-pages, page selection for multi-page inputs (e.g. PDFs): --pages 1,3,5-7, --pages 2-, keywords odd/even.
• --include-structuring / --exclude-structuring, structuring operations that infer document structure (sections, abstracts, references) from loosely structured input. Example: --include-structuring sections-to-abstract.
• --ignore-artifacts, re-download / re-process instead of using cached intermediate artifacts in .stencila/artifacts/.

Ingesting published papers