Home

stencila render

Render a document

Usage

stencila render [OPTIONS] [INPUT] [OUTPUTS]... [-- <ARGUMENTS>...]

Examples

# Render a document and preview in browser
stencila render document.smd

# Render to a specific output format
stencila render report.md report.docx

# Render to multiple formats
stencila render analysis.md output.html output.pdf

# Render from stdin to stdout
echo "# Hello" | stencila render --to html

# Render with document parameters
stencila render template.md output.html -- --name="John" --year=2024

# Render ignoring execution errors
stencila render notebook.md report.pdf --ignore-errors

# Render and cache a document
stencila render temp.md output.html --cache

# Spread render with multiple parameter combinations (grid)
stencila render report.md 'report-{region}-{species}.pdf' -- region=north,south species=ABC,DEF

# Spread render with positional pairing (zip) and output to nested folders
stencila render report.md '{region}/{species}/report.pdf' --spread=zip -- region=north,south species=ABC,DEF

# Spread render with explicit cases
stencila render report.md 'report-{i}.pdf' --spread=cases --case="region=north species=ABC" --case="region=south species=DEF"

Arguments

NameDescription
[INPUT]The path of the document to render.
[OUTPUTS]The paths of desired output files.
[ARGUMENTS]Arguments to pass to the document.

Options

NameDescription
--spreadEnable multi-variant (spread) execution mode.
--spread-maxMaximum number of runs allowed in spread mode (default: 100). Default value: 100.
--caseExplicit parameter sets for cases mode.
--cacheCache the document after rendering it. Possible values: true, false.
--ignore-errorsIgnore any errors while executing document. Possible values: true, false.
--force-allRe-execute all node types regardless of current state. Possible values: true, false.
--skip-codeSkip executing code. Possible values: true, false.
--skip-instructionsSkip executing instructions. Possible values: true, false.
--retain-suggestionsRetain existing suggestions for instructions. Possible values: true, false.
--force-unreviewedRe-execute instructions with suggestions that have not yet been reviewed. Possible values: true, false.
--force-acceptedRe-execute instructions with suggestions that have been accepted. Possible values: true, false.
--skip-rejectedSkip re-executing instructions with suggestions that have been rejected. Possible values: true, false.
--dry-runPrepare, but do not actually perform, execution tasks. Possible values: true, false.
-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.
-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.
--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.

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 --spread

ValueDescription
gridCartesian product of multi-valued parameters (default)
zipPositional pairing of multi-valued parameters
casesExplicitly enumerated parameter sets via --case

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