# Authoring

How to write Stencila Markdown (.smd) and work with executable documents in related...

- Repository: https://github.com/stencila/stencila (914 stars)
- Category: Writing
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add stencila/stencila --skill authoring -g -a claude-code -y`
Codex: `npx skills add stencila/stencila --skill authoring -g -a codex -y`
Cursor: `npx skills add stencila/stencila --skill authoring -g -a cursor -y`
Gemini CLI: `npx skills add stencila/stencila --skill authoring -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add stencila/stencila`

## Description

How to write Stencila Markdown (.smd) and work with executable documents in related flavours (.myst, .qmd). Use when creating or editing .smd files, adding executable code chunks, inline expressions, parameters, figures, tables, math, or document metadata, or when unsure how Stencila Markdown differs from plain Markdown.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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:

```sh
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:

````smd
```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):

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

### Inline expressions

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

```smd
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`:

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

### Frontmatter

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

The rest: https://github.com/stencila/stencila/blob/HEAD/claude/skills/authoring/SKILL.md