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, so the table shows the idiomatic choice rather than an enforced one.
A space between the comment marker and the pipe is tolerated (# | echo: false,
// | name: x), but the canonical form is tight.
11.1.1 The leading-block rule
Options are read only from the contiguous run of directive lines at the very 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 the label is invisible to Taliesin, 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 just an ordinary comment.
11.1.2 Unknown keys are caught
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`?)
The cell still renders exactly as before; the warning just 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 source listing; the cell still runs and its output still shows |
include | python | 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 | (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 imply a
number even without a label: the caption alone is enough to make a numbered
figure, table, or listing. 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,
it just can’t be referenced.
For the full explanation of echo, include, and cache, including the cache
key’s one blind spot, 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 / include / cache (which are about the
Python kernel) are not honoured on a {js} cell: it renders only its output container,
and its source is never shown as a listing, so there is nothing for echo to hide.
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.