Reference

Every option the cascade extension accepts.

The complete cascade behaviour: every option, the per-heading attribute and class, how divs are handled, and what happens outside RevealJS.

Enabling the filter

filters:
  - cascade

Options

extensions:
  cascade:
    depth: 1
    keep-hrule: false
    shift: 0

Document and project options.
Option	Type	Default	Description
`depth`	integer	unset	How many levels of the chain to repeat, counted from the slide level. Unset repeats the whole chain, and `0` repeats none of it.
`keep-hrule`	boolean	`false`	Whether `---` survives in formats other than RevealJS. Only the literal `false` turns it off; any other value is read as `true`.
`shift`	integer	`0`	The `shift-heading-level-by` applied to the document. May be negative.

Only headings at or below the slide level are ever repeated. A # above the slide level starts its own section slide and is not carried onto a continuation, whatever depth says.

A heading joins the chain when it comes directly after the slide-level heading, directly after another heading, or directly after a --- the filter absorbed. A heading written after body text is not collected, and is not repeated. A heading under a --- the filter passed over is not collected either, since that rule started no chain. A heading marked .no-cascade stays out of the chain, and does not stop the heading written under it from joining.

The repeated slide-level heading is what starts the continuation slide. The filter takes a --- out of the document only while the chain holds at least one heading. So a --- whose chain holds headings, none of them at slide level, starts no slide, and the content under it stays on the slide above. A --- whose chain is empty stays in the document instead, and RevealJS starts a slide with no heading on it.

What the chain holds changes as the document goes. A heading above the slide level clears it. A slide-level heading restarts it from the headings above that level. A heading marked .no-cascade stays out of it. Each repeat then replaces the chain with the headings that repeat wrote, which can be none: depth: 0 and cascade-depth="0" write none, and a --- followed by a heading writes only the headings above that heading’s level.

A repeated heading is a copy with its identifier removed, so it carries no anchor of its own and the original heading keeps the only link to that section.

Shifted heading levels

The filter has to know which heading level makes a slide, and it works that out from the RevealJS slide-level, 2 unless the document says otherwise. shift-heading-level-by moves every heading under that line, and Quarto treats it as a Pandoc option: it is applied after the filter has run and is passed to no filter, whether it is written at the top of the document or under a format. A document that sets it therefore has to say so a second time.

extensions:
  cascade:
    shift: -1

format:
  revealjs:
    shift-heading-level-by: -1

Leave the two out of step and the chain is read one level off: the heading that starts a section is treated as a slide heading and repeated, so each --- produces a duplicate section slide.

Per-heading control

The attribute and the class.
Written on a heading	Effect
`{cascade-depth="1"}`	Overrides `depth` for the chain starting at that heading.
`{.no-cascade}`	The heading keeps its place in the source, and is never carried forward.

An override applies to the chain that begins at the annotated heading. The document-level setting resumes at the next heading at or above slide level.

A heading below the slide level marked .no-cascade keeps its own place in the slide, and the --- under it still starts a slide from the rest of the chain. A slide-level heading marked .no-cascade leaves the chain without a heading at slide level, so a --- under it starts no slide while the chain still holds a heading below that level. With nothing else in the chain the --- survives instead, and starts a slide with no heading on it.

Divs

A --- inside a div splits the slide there too: the div is closed, the chain repeated, and an identical div reopened around what follows.

## Results

::: {.column-margin}

A side note, first part.

---

Second part, still in the margin, on a new slide.

:::

Each reopened div is a copy of the first with its identifier removed, so a div written with an #id keeps it on the first slide only.

When the div opens with a heading, that heading is repeated inside every reopened div, with its identifier removed. A callout whose title is written as a heading therefore keeps that title on continuation slides, instead of falling back to the generic name of its type.

Two kinds of div are left alone, because reopening them would break them:

.panel-tabset;
any div whose identifier begins with letters followed by a hyphen. This is meant to catch a cross-reference target such as #tbl-results or #fig-plot, and it catches an ordinary identifier of the same shape, such as #side-note, as well.

What is not a slide break

Horizontal rules that are not breaks.
Where the `---` is	What happens
In a fenced code block	Pandoc treats it as content, so the filter never sees it.
In a pipe table	It is a column separator, and is left alone.

What is reported

The filter reports four things, and none of them stops the render:

a cloned chain that skips a heading level, a ## followed by a #### with no ### between, which usually points at an accidental gap in the source;
a depth or a cascade-depth that is not a whole number of zero or more. The attribute falls back to the document setting, and the option to repeating the whole chain;
a shift that is not a whole number, which is ignored in favour of 0;
a shift that moves the slide level outside the range 1 to 6, which would leave every chain empty and repeat nothing, and is ignored in favour of 0.

The extension also checks what the document wrote against its own schema, before the filter reads an option. A key the schema does not declare in extensions.cascade is reported as a warning, and ignored. A value there of a type the schema does not accept is reported as an error, and the render still completes. A cascade-depth the schema does not accept is reported as a warning, since the attribute only ever overrides the document setting and the filter falls back to it.

One mistake can therefore produce two messages. A depth, a shift, or a cascade-depth the schema rejects is named by the schema check, and then by the filter, which says what it does instead. A keep-hrule the schema rejects is named by the schema check alone, since the filter reads every value other than false as true and has nothing to add.

The Examples page shows the source behind each of these messages, and what the render log says.

Outside RevealJS

--- is removed by default, since nothing there splits into slides.

extensions:
  cascade:
    keep-hrule: true

keeps the horizontal rules as rules.

Limitations

RevealJS only. Elsewhere the filter either removes the rules or leaves them, and repeats nothing.
.panel-tabset and cross-reference divs are not split.