Authoring Stencila documents

Stencila Markdown (.smd) is CommonMark plus a small set of extensions for executable, reproducible documents. Stencila also parses MyST (.myst) and Quarto (.qmd) Markdown; prefer .smd for new documents unless the user already works in one of those ecosystems, in which case keep their format. The Markdown parser auto-detects the flavour, so --from is rarely needed.

Minimum CLI version: 2.14. Verify a document parses with:

NO_COLOR=1 stencila convert doc.smd --to json --yes > /dev/null

What differs from CommonMark

The constructs below are the ones worth double-checking; everything else (headings, emphasis, links, lists, block quotes) is standard Markdown.

Executable code: exec

A fenced code block with the exec keyword executes when the document is rendered, and its outputs become part of the document:

```python exec
import pandas as pd
data = pd.read_csv("data.csv")
data.describe()
```

Without exec a code block is static, display-only code. Do not confuse exec with demo: demo parses-and-renders the block content as document source without executing anything, it is for documentation that shows source alongside rendered output.

Execution modes go after exec (e.g. always to re-run on every execution, lock to preserve existing outputs):

```r exec always
plot(data)
```

Inline expressions

Backtick code with a language tag and exec in braces embeds a computed value in prose:

The answer is `6 * 7`{python exec}.

Without exec (e.g. `2 * pi`{python}) it is just static inline code with a language.

Parameters

Named inputs that can be supplied at render time with stencila render doc.smd out.html -- --name=value:

Analysis for &[year]{int def=2024} using threshold &[cutoff]{num def=0.05}.

Frontmatter

YAML frontmatter carries metadata (title, authors, description):