Home

stencila convert

Convert a document to another format

Usage

stencila convert [OPTIONS] [INPUT] [OUTPUTS]... [-- <TOOL_ARGS>...]

Examples

# Convert Stencila Markdown to MyST Markdown
stencila convert document.smd document.myst

# Convert to multiple output formats
stencila convert input.smd output.html output.pdf output.docx

# Specify input and output formats explicitly
stencila convert input.txt output.json --from plain --to json

# Convert with specific codec options
stencila convert doc.md doc.html --standalone

# Convert only specific pages from a PDF
stencila convert document.pdf extract.md --pages 1,3,5-10

# Convert all pages except specific ones
stencila convert report.pdf content.md --exclude-pages 5,15

# Convert only odd pages from a document
stencila convert book.pdf odd-pages.md --pages odd

# Use an external tool like Pandoc
stencila convert doc.md doc.tex --tool pandoc

# Pass arguments to external tool
stencila convert doc.md doc.pdf --tool pandoc -- --pdf-engine=xelatex

# Convert from stdin to stdout (defaults to JSON)
echo "# Hello" | stencila convert

Arguments

NameDescription
[INPUT]The path, URL or other identifier for the input file.
[OUTPUTS]The paths of desired output files.
[TOOL_ARGS]Arguments to pass through to the tool using for encoding.

Options

NameDescription
-f, --fromThe format of the input/s.
--fineUse fine decoding if available for input format. Possible values: true, false.
--coarseUse coarse decoding if available for input format. Possible values: true, false.
--pagesPages to include when decoding multi-page documents.
--exclude-pagesPages to exclude when decoding multi-page documents.
--ignore-artifactsIgnore cached artifacts and force re-processing. Possible values: true, false.
--no-artifactsPrevent creating artifacts during decoding. Possible values: true, false.
--island-wrapWrap specified environments in Island nodes during decoding. Default value: figure,table,longtable,landscape.
--no-island-wrapDisable automatic Island wrapping of environments. Possible values: true, false.
--island-styleStyle to apply to auto-created Island nodes.
--input-lossesAction when there are losses decoding from input files. Default value: debug.
--include-structuringStructuring operations to include (comma-separated).
--exclude-structuringStructuring operations to exclude (comma-separated).
--citation-styleThe citation style to assume for text-to-citation structuring.
--strip-scopesScopes defining which properties of nodes should be stripped.
--strip-typesA list of node types to strip.
--strip-propsA list of node properties to strip.
-t, --toThe format of the output/s.
--templateThe template document to use.
--reproducibleEncode executable nodes so that they are reproducible. Possible values: true, false.
--highlightHighlight the rendered outputs of executable nodes. Possible values: true, false.
--no-highlightDo not highlight the rendered outputs of executable nodes. Possible values: true, false.
--standaloneEncode as a standalone document. Possible values: true, false.
--not-standaloneDo not encode as a standalone document when writing to file. Possible values: true, false.
--themeThe CSS theme to use when encoding to HTML and HTML-derived formats.
--viewThe document view to use when encoding to HTML and HTML-derived formats.
--embed-mediaEmbed media files as data URIs. Possible values: true, false.
--extract-mediaExtract embedded media to a folder.
--embed-supplementsEmbed supplemental files directly into the document. Possible values: true, false.
--extract-supplementsExtract embedded supplemental content to separate files.
--recursiveRecursively encode the content of IncludeBlocks to their source file. Possible values: true, false.
--compactUse a compact form of encoding if available. Possible values: true, false.
--prettyUse a "pretty" form of encoding if available. Possible values: true, false.
--output-lossesAction when there are losses encoding to output files. Default value: debug.
--from-toolThe tool to use for decoding inputs.
--toolThe tool to use for encoding outputs (e.g. pandoc).

Possible values of --citation-style

ValueDescription
author-yearAuthor-year citations like (Smith, 2023)
bracketed-numericBracketed numeric citations like [1]
parenthetic-numericParenthetic numeric citations like (1)
superscripted-numericSuperscripted numeric citations like ¹

Possible values of --strip-scopes

ValueDescription
authorsStrip authorship properties of nodes
provenanceStrip provenance properties of nodes
metadataStrip metadata properties of nodes
contentStrip content properties of nodes
archiveStrip archive properties of nodes
temporaryStrip temporary properties of nodes
codeStrip code properties of executable nodes
compilationStrip compilation related properties of executable nodes
executionStrip execution related properties of executable nodes
outputStrip output properties of executable nodes
timestampsStrip timestamp properties

Possible values of --include-structuring, --exclude-structuring

ValueDescription
noneNo structuring operations
allAll structuring operations
sections-to-keywordsExtract keywords from the "Keywords" section
sections-to-abstractExtract abstract from the "Abstract" section
sections-to-referencesExtract references from "References" section
headings-to-titleExtract document title from the first heading
heading1-to-titleExtract document title from the very first level 1 heading
heading1-to-title-singleExtract document title from a single level 1 heading (conservative)
headings-decrementDecrement all heading levels by 1 (H2→H1, H3→H2, etc.)
headings-primary-level1Ensure that all "primary" headings have level 1
headings-to-sectionsCreate a section for each heading
headings-to-paragraphsTransform headings to paragraphs if appropriate
paragraphs-to-keywordsExtract keywords from paragraphs starting with "Keywords"
paragraphs-to-headingsTransform paragraphs to headings if appropriate
paragraphs-to-sentencesSplit paragraphs into individual sentences
figures-with-captionsCombine an image with a figure caption before or after it
tables-with-captionsCombine a table caption with the following table or datatable
table-images-to-rowsConvert table images to table rows using OCR
tables-to-datatablesTransform tables into datatables if possible
unwrap-media-objectsUnwrap media objects from paragraphs to block level
unwrap-quote-blocksUnwrap quote blocks containing more than two child blocks
text-to-citationsConvert text to structured citations
text-to-linksConvert URL text to structured links
math-to-citationsConvert math to structured citations
math-images-to-texConvert math images to TeX code using OCR
links-to-citationsConvert links to citations
normalize-citationsNormalize citation formatting and grouping
remove-pre-primaryRemove content before the first primary heading
remove-frontmatter-duplicatesRemove front matter that duplicates article metadata
remove-empty-headingsRemove empty headings
remove-empty-tablesRemove empty tables and datatables
remove-empty-listsRemove empty lists
remove-empty-paragraphsRemove empty paragraphs
remove-empty-textRemove empty text
© 2026 Stencila