Stepper

Render an ordered sequence of steps with one step at a time + Prev/Next paging. Best for tutorials / setup wizards / cooking recipes / algorithm walkthroughs — explicitly tells the reader "follow this path, in order."

When to use

• ✅ Tutorials (install → configure → first use)
• ✅ Multi-stage flows (multi-step forms / onboarding wizards / deploy checklists)
• ✅ Algorithm walkthroughs (one step at a time, see state changes)
• ✅ Cooking / experiment steps (ingredients → prep → cook → plate)
• ❌ Pick one of several views (not a sequence — parallel choices) → use Tabs
• ❌ Time-ordered events (history / roadmap with dates) → use Timeline
• ❌ Order doesn't matter (steps in any order) → use Layout or a plain list

Basic syntax

```stepper
:::step title="Open Rho MD"
Launch the app.
:::

:::step title="Open a .md file"
File → Open → pick your `.md`
:::

:::step title="Start writing"
Write markdown / AINP directly in the editor.
:::
```

Renders: a top progress bar showing "Step 1 of 3", below it one step at a time; bottom Prev / Next buttons to page through.

All options

Block-level: ```stepper

Step-level: :::step

Quote title if it has spaces: title="Open a .md file".

Examples

Example 1: 3-step tutorial

```stepper
:::step title="Step 1: Install"
Open a terminal (installing a hypothetical tool "acme"):

```bash
brew install acme      # macOS
sudo apt install acme  # Ubuntu/Debian
```
:::

:::step title="Step 2: Create your first file"
```bash
echo "# Hello" > demo.md
acme demo.md
```

The app opens a window showing the rendered output.
:::

:::step title="Step 3: Write your first interact block"
Add this to `demo.md`:

```\```interact
slider x range=0..10 step=1 default=5
template stl:
[Selected] -> [{x}]
```\```

Reload — you'll see a slider.
:::
```

Renders: top "Step 1 of 3" → "Step 2 of 3" → "Step 3 of 3" progress bar; click Next to advance. Each step holds rich markdown (code blocks, nested fences).

Example 2: linear wizard (onboarding)

```stepper linear=true
:::step title="Welcome"
🎉 Welcome to Rho! This wizard takes 5 minutes to set up the basics.

Click **Next** to continue.
:::

:::step title="Account"
Enter your email (used for rho.md sync):

```interact
input email default="you@example.com" label="Email"
template stl:
[Email] -> [{email}]
```
:::

:::step title="Theme preference"
```interact
select theme options=dark,light,system default=dark
template stl:
[Theme] -> [{theme}]
```
:::

:::step title="Done"
✅ All set. Click **Done** to enter the main UI.
:::
```

Renders: 4-step strict linear wizard; can't skip ahead until the previous step is done. Pairs with interact controls for lightweight forms (note: state isn't actually submitted to a backend — pure client-side, just a UI demo).

Example 3: algorithm walkthrough (with state)

```stepper
:::step title="Initial array"
Original array: `[5, 2, 8, 1, 9, 3]`

We'll bubble-sort: compare adjacent pairs, larger sinks.
:::

:::step title="Pass 1"
Compare:
- (5,2) → swap → `[2, 5, 8, 1, 9, 3]`
- (5,8) → no change
- (8,1) → swap → `[2, 5, 1, 8, 9, 3]`
- (8,9) → no change
- (9,3) → swap → `[2, 5, 1, 8, 3, 9]`

The maximum 9 has "sunk" to the end.
:::

:::step title="Pass 2"
Repeat over the first 5 elements ...
:::

:::step title="Done"
Sorted: `[1, 2, 3, 5, 8, 9]`
:::
```

Renders: algorithm step-through showing intermediate state per pass. Much clearer than one block of static prose.

Plain-text fallback behavior

:::step is a markdown directive container. In readers without support:

:::step title="Step 1: Install"
content
:::

→ :::step title=... shows as a literal; step content renders normally. All steps expand inline as a long page — readers see every step, only losing the "one step at a time + paging" interactivity.

Per-reader breakdown:

Readers always see all steps — that's the point of plain-text fallback.

Common pitfalls

1. Steps out of order

```stepper
:::step title="Step 3"
:::
:::step title="Step 1"
:::
:::step title="Step 2"
:::
```

→ Rho renders in document order (no auto-sort). Order them before you write.

2. Too many steps

3. Wildly uneven step content

```stepper
:::step title="Step 1"
(10 paragraphs of dense prose)
:::
:::step title="Step 2"
Click Next.
:::
:::step title="Step 3"
(8 more paragraphs)
:::
```

→ Progress bar lies — 5 steps look even, but the actual workload is wildly different. Keep each step roughly equal effort (< 3 min reading / 1-2 actions).

4. Missing ::: close

```stepper
:::step title="A"
A content
                ← ❌ Missing :::
:::step title="B"
B content
:::
```

→ The whole stepper fails to parse. Every :::step needs a paired :::.

5. linear=true but user has no Skip path

```stepper linear=true
:::step title="Required email"
```interact
input email default=""    ← ⚠️ No default; user didn't fill in but can't skip → stuck
template stl:
[Email] -> [{email}]
```
:::
```

→ In linear mode the user can't advance without filling email, but Rho doesn't auto-validate input. Linear steps must:

• Give every control a sensible default value, or
• Don't use linear mode

6. stepper inside stepper

```stepper
:::step title="Outer"
```stepper       ← ⚠️ stepper in stepper; UI gets confusing fast
```
:::
```

→ Technically supported by Nested DSL, but two progress bars compete visually. Improvement: use Tabs inside, or replace with a plain ordered list.

7. Step 1 is "intro," not an action

```stepper
:::step title="Intro"
This is a Rho onboarding tutorial......(200 words of intro)
:::
:::step title="Step 1: Install"
...
:::
```

→ Users land on step 1 expecting an "action," see a wall of prose, get confused. Improvement: put the intro before the stepper as a regular paragraph; step 1 is the first action.

Stepper vs Tabs vs Timeline — how to choose

See also

• Tabs — Multi-view, same space (unordered)
• Modal — Hidden content, on-demand
• Timeline — Time sequence (not a tutorial)
• Interact controls — Embedding input/select in steps for light forms
• Nested DSL
• Plain-text fallback principle