Feature Blocks — Treat Code Fences Like a Command Line for Markdown

Here’s a small idea for big clarity: treat fenced code blocks as designated enhancement zones — tiny, bounded places where we can add interactivity safely — by letting the fence’s info string behave like a command line.

The Problem With “Advanced Documents”

Docs get messy when features bleed everywhere: global scripts, invisible state, and behaviors that pop out of nowhere. Authors worry about breaking the reading flow, and implementers end up bolting on ad‑hoc rules. We don’t need “advanced documents”; we need small upgrade islands with clear boundaries.

The Model: Feature Blocks

A feature block is just a fenced code block whose info string is treated like a tiny command line that configures a self‑contained widget. Interactivity is limited to the block’s rectangle — no global reach, no surprise side‑effects.

``` typing -include-metric="wpm" -max-errors=3 -theme="minimal"
// Any inner text can be prompt or seed data
// Example: the learner types this paragraph and the block tracks speed and accuracy.
Practice makes patterns. Patterns make recovery fast.
```

Read it like a CLI: the typing program with flags -include-metric, -max-errors, and -theme. Unknown programs or flags simply fall back to a normal code fence.

Why a CLI‑Style Info String?

• Discoverable — authors can skim fences and “read the command”.
• Composable — flags give you small, orthogonal options.
• Versionable — add -v or --spec=1 without breaking earlier docs.
• Portable — plain Markdown still renders; unsupported engines show the raw code.

Design Principles

• Bounded scope — behavior lives entirely inside the block.
• Deterministic — no hidden network calls by default; inputs are explicit.
• Graceful fallback — if unrecognized, render as a normal code fence.
• Accessible — keyboard‑first, themable, with semantic labels.

Examples

1) Typing Drill

``` typing -include-metric="wpm,accuracy" -prompt="Type the paragraph" -max-errors=5
Pattern typing builds rhythm, chunking, and recovery.
```

Renders an inline typing game that reports WPM and accuracy. All effects are local to the block.

2) Callout / Admonition

``` callout -kind="tip" -icon="sparkle"
Keep interactivity inside the fence — your readers will thank you.
```

Displays a stylized, accessible callout. Outside the block, the doc remains static and predictable.

3) Local Include

``` include -path="docs/snippets/setup.sh" -lang="bash"
```

Inserts a local snippet at build time. No runtime network I/O; fails closed if the file is missing.

Authoring Guidelines

• Prefer short, purposeful blocks; one idea per block.
• Document flags inline with a brief comment header.
• Provide a non‑interactive fallback experience (e.g., final score, static callout text).
• Keep inputs explicit; no implicit fetches.

Takeaway

Treating code fences like a tiny command line gives us a clean mental model: interactive where designated, stable everywhere else. Authors keep control, readers keep flow, and implementers get a small, testable surface.