11 Cell-options reference
Every cell option and what a label decides, including why the cache key sees your code rather than your data.
Reference: Cheat sheet · CLI · Configuration · Cell options · Troubleshooting · Accessibility · Licensing
A code cell carries per-cell options on its leading comment lines. These tune
whether the source shows, whether the cell runs, whether its output is cached, and
how the output is captioned, numbered, and cross-referenced. This page is the
complete list. For the narrative on writing and running cells, see
Executable content; for the document-wide execute: defaults
that cell options override, see the
Configuration reference.
11.1 How options are written
An option is a key: value line at the top of the cell, behind a directive
prefix. By convention the prefix is the cell’s own comment marker plus a pipe:
| Cell language | Prefix | Example |
|---|---|---|
{python} | #| | #| echo: false |
{js} | //| | //| viewof: harmonics |
{mermaid} | %%| | %%| label: fig-flow |
Picking the cell’s own comment marker keeps the option line a valid comment in that
language. All three prefixes (#\|, //\|, %%\|) are accepted regardless of the
cell’s language; the table shows the idiomatic choice for each language.
A space between the comment marker and the pipe is tolerated (# | echo: false,
// | name: x), but the canonical form is tight.
A value follows YAML’s comment rule: a # after whitespace starts a comment, so
#| echo: false # hide setup reads false. A caption that contains # goes in quotes
(#| fig-cap: "Run #3").
11.1.1 The leading-block rule
Options are read only from the contiguous run of directive lines at the top of the cell. The first line that is not an option directive stops option parsing, and everything from there on is treated as code. So this works:
#| echo: false
#| label: fig-loss
But here Taliesin ignores the label, because a blank line (and then real code)
already ended the option block:
#| echo: false
#| label: fig-loss
Keep every option line flush against the top of the cell with no blank line between them. A directive that appears after code is an ordinary comment.
11.1.2 Unknown keys
The option vocabulary is closed. A key Taliesin does not recognize (a typo, or an option it does not implement) is reported as a located warning with a “did you mean” hint when a known key is within edit distance 2:
notes.tmd:14: unknown cell option `labl` (did you mean `label`?)
A known option that does nothing on its cell (echo or cache on a {js} cell, name,
viewof or input on any other cell, echo on a listing) and a label without a
fig-, lst- or tbl- prefix also draw a located warning. A key set twice in one cell
is read from its first line only, and each later line draws a located warning.
The cell still renders as before; the warning only points at the line.
11.2 Every option
An option marked (none) in the Default column does nothing unless you set it.
| Option | Languages | Default | Effect |
|---|---|---|---|
echo | python | true | false hides the cell’s source; the cell still runs and its output still shows. No effect on a listing or a {js} cell |
include | python, js | true | false hides both source and output; the cell still runs (kernel state is kept) |
cache | python | true | false opts the cell out of the _freeze/ cache, so it always re-executes |
label | python, mermaid, js | (none) | fig-X / lst-X / tbl-X makes the cell a numbered, cross-referenceable figure / listing / table (resolve with @fig-X etc.) |
fig-cap | python, mermaid, js | (none) | A caption for the output; also turns the output into a numbered <figure> |
lst-cap | python, js | (none) | A caption for the source listing, making it a numbered listing |
tbl-cap | python | (none) | A caption for the output table, making it a numbered table |
code-fold | python | (none) | true collapses the listing into a closed <details>; show folds it but starts open |
code-summary | python | "Code" | The summary label for a code-fold listing |
name | js | (none) | Publish the cell’s return value into the reactive scope under this name (a helper other {js} cells read) |
viewof | js | (none) | The cell returns a DOM input; its value is registered under this name for other cells to consume |
input | js | (none) | Comma-separated names; re-run this cell when any named input, viewof, or Python define value changes |
Anything not in this list warns. fig-cap / tbl-cap / lst-cap each make a
numbered figure, table, or listing even without a label. Add a label only when you
want to cross-reference it.
A label: selects which numbered thing the cell becomes. fig-, lst-, and
tbl- prefixes route to figure, listing, and table respectively, so a labelled
cell’s caption shows up in the matching numbering and @fig-/@lst-/@tbl-
references resolve to it. A bare fig-cap with no label still numbers the figure,
but nothing can reference it.
For the full explanation of echo, include, and cache, including the inputs
the cache key ignores, see Executable content.
The document-wide execute: default (cache: only) is in the
Configuration reference.
11.3 {js} reactive options
name, viewof and input wire a cell into the in-browser reactive graph instead of
the kernel. They run client-side, so echo and cache (which are about the Python
kernel) are not honoured on a {js} cell: a running cell renders only its output
container, so there is nothing for echo to hide. A {js} listing or table cell
(lst- / tbl-) never runs and always shows its source, which only include: false
hides.
The two readers of the graph are not interchangeable. tali.value("NAME") reads an
input value: a viewof, an {{< input >}} control, or a define value.
tali.get("NAME") reads a value published by another cell’s //| name:.
A dangling //| input: and a cycle between {js} cells are both publish-blocking lints,
described in the CLI reference. For the full reactive walkthrough, see
Interactive and explorable documents.