Skip to content

Autoflow

Autoflow analyzes plain markdown and infers the best layout for each slide. No directives needed — just write text, and StellarDeck chooses headings, positioning, alignment, and emphasis. Convention over configuration for slide design.

Navigate the deck above to see autoflow in action. Every slide was written as plain paragraphs — autoflow added all the layout directives.

Each slide passes through a pipeline before the parser runs:

  1. Skip checks — slides whose text you already laid out (#[fit], position modifiers, [.autoscale]), code fences, or custom blocks (:::columns) are left alone.
  2. Preprocessing — images are set aside so the rules see only the words. An explicit ![right]/![left]/![fit]/![filtered] stays exactly as written; a bare ![](src) with a few words becomes a dark-filtered hero background.
  3. Rule matching — the slide is tested against each rule in priority order. First match wins. Rules that need the whole slide (diagonal, Z-pattern, alternating) sit out on split slides.
  4. Directive injection — the matched rule injects directives into the raw markdown. The parser handles them normally.

Autoflow never invents content. It only adds the same directives you would write by hand.

Nine rules, evaluated in this order:

RuleWhen it matchesWhat it does
TitleFirst slide, 2+ paragraphs, short title line#[fit] centered title, normal subtitle
DividerSingle line, 1-2 words#[fit] heading, centered
Diagonal2 paragraphs, at least one ends with ?Top-left + bottom-right positioning
Z-PatternExactly 4 short paragraphsFour corners: TL, TR, BL, BR
Alternating3+ short paragraphsAccent color rotation
Statement1-4 short lines (up to 8 words; 15 as a dense block)#[fit] headings, alignment varies
Image + textOne bare image + more than 8 words![inline] → ![left] → ![right] across the deck (a few words: filtered hero background)
Phrase + bulletsOne short heading + 2-3 short bulletsCards, pills, alternating, or staggered — rotates across the deck
AutoscaleMore than 8 lines or 80+ words[.autoscale: true]

The first slide gets special treatment. A short opening line followed by longer paragraphs becomes a #[fit] title with subtitle text.

slide.md
Punch **Slides**

Bold text-only slides for **storytelling**.
No images needed — just **words** and **rhythm**.

Two paragraphs where at least one contains a question. Positioned on opposite corners for Z-axis reading flow.

slide.md
What is **distraction** and what is **disruption**?

**Arrogance** or **procrastination**?

Short plain-text lines (1-4 lines, up to 8 words each) become #[fit] headings that fill the slide. Denser lines (up to 15 words) scale together as one block instead.

slide.md
Think **big**.
Act **small**.

A single line with one or two words becomes a full-width #[fit] heading. Perfect for section breaks.

slide.md
**Learn** fast.

When autoflow detects a bare image and text on the same slide, it looks at how much text there is. A few words (8 or fewer) make a hero: the image becomes a dark-filtered background and the words go big on top. More text gets a split layout — image on one side, text on the other — and the side alternates between slides (a title plus one line can also sit inline, with the image in the flow).

slide.md
![](images/coaches/yuval-ayalon.webp)

The discipline of hand balancing
requires years of patient,
consistent practice.

A few words over the same photo make a hero:

slide.md
![](images/coaches/yuval-ayalon.webp)

Years of practice.

When consecutive slides match the same rule, autoflow varies their presentation:

  • Statements rotate alignment: center, left, right.
  • Diagonals mirror corner positions: TL/BR becomes TR/BL on the next diagonal.

Based on Steven Bradley’s alternating rhythm principle — visual variety within structural consistency.

Three ways to turn it on:

Frontmatter — add autoflow: true at the top of your markdown:

footer: My Talk
autoflow: true
First slide content here.

Toolbar — click the Autoflow toggle in StellarDeck’s toolbar. Saves the preference to the sidecar file.

Sidecar — autoflow state persists in .stellar.json alongside your .md file:

{
"autoflow": true,
"theme": "Nordic, 1",
"lastSlide": 0
}

The sidecar approach means autoflow never modifies your markdown. Layout inference is a presentation-time concern.

Autoflow respects your choices. If you place an image explicitly (![right], ![left], ![fit], ![filtered]), autoflow leaves the image exactly where you put it — and still lays out the words beside it, so a short line next to ![right] becomes a statement. If you lay out the text yourself (#[fit], #[top-left], [.autoscale]), autoflow leaves that slide alone. You fully opt out with autoflow: false in frontmatter.

Autoflow rules are actively improving. Each rule is a small declarative object in its own file (packages/core/src/autoflow/rules/), so new ones — a lone URL becoming a QR code, aspect-ratio aware image layouts — can be added without touching the others, and existing rules may be refined. In a future version, rules will be individually configurable via presets (Storyteller, Presenter, Dense) or per-rule overrides.

The current rule set is stable for production use — changes are additive and backward-compatible.