A terminal walkthrough
is just <x-zsh>

Why x-zsh

Recording a terminal is fiddly and the output is a video you can't copy from. x-zsh is just markup — versionable, themeable, and the commands stay selectable.

Install

Pick a CDN tag or install from npm. The script auto-registers the <x-zsh> element on load — there's nothing to initialize.

CDN (fastest)

<!-- unpkg, latest (minified) -->
<script src="https://unpkg.com/x-zsh"></script>

<!-- or jsDelivr, pinned to a version -->
<script src="https://cdn.jsdelivr.net/npm/x-zsh@0.6/x-zsh.min.js"></script>

npm

npm install x-zsh

// side-effect import registers <x-zsh>
import 'x-zsh';

Then write a session

<x-zsh os="ubuntu" plugins="node">
  cmd: npm create vite@latest my-app
  success: ✔ Scaffolding project...
  cmd: cd my-app && npm install
  progress[2s]: Installing
</x-zsh>

Examples

Each terminal has a fixed height, so it scrolls internally and never makes the page jump. Scroll one into view to play it.

Python · pip progress · light mode

Docker · spinners · looping with controls

git workflow · error then recovery

All five progress-bar styles

Rich prompt — Rocky Linux · Go · Terraform · Kubernetes · AWS

Pinned versions & a custom plugin

Named themes — theme="dracula", theme="catppuccin", …

Right-side tail — clock + last-command status

Compact — icons only (compact)

User guide

The content between the tags is a tiny line-based language. Each line is an input the user types, an output the program prints, or a directive. Indentation is stripped, so you can nest it neatly in your HTML.

The one rule

A bare line is stdout of the command above it. You only reach for a verb when a line isn't plain output. Only the reserved words below (lowercase, followed by :) are treated as verbs — any other word: renders as ordinary output, so no escaping.

Input

Output

Time & effects

Screen & context

Durations & styles

The bracket on timed verbs holds a duration and/or a style, in any order: progress[3s pip], spinner[1.5s line]. Durations accept 800 (ms), 800ms, 2s, 1.5s.

Spinner styles: dots (default), line, bar, arc, circle.

Attribute reference

All attributes are optional. Set them on the <x-zsh> tag.

It plays when scrolled into view and respects prefers-reduced-motion (renders instantly, no animation).

Dev guide

It's a single dependency-free file — a custom element, a line parser, and an async render loop. Hack on it in minutes.

Run the docs locally

git clone https://github.com/i-rocky/x-zsh
cd x-zsh
# any static server works
python3 -m http.server 8000
# open http://localhost:8000

How it works

• Parse — the tag's text is dedented and each line classified into {verb, dur, style, text}.
• Mount — a Shadow DOM is attached; all CSS lives in one :host stylesheet so nothing leaks.
• Run loop — an async chain renders one item at a time. A run-token guards against overlapping playback when you replay or step.
• Effects — typing, spinners and progress are cancelable, so pause/step snaps them to their final state instantly.

Theming

Use a built-in palette with theme="…" (tokyonight, dracula, nord, catppuccin, gruvbox, solarized, onedark, rosepine), register your own, or override the CSS custom properties directly — they're all themeable:

// keys: bg fg muted accent accent2 ok warn err info comment dir git
XZsh.theme('mytheme', { bg: '#101418', fg: '#e6edf3', accent: '#3fb950' });

x-zsh::part(window){ border-radius: 6px; }
x-zsh{ --bg:#1e1e2e; --fg:#cdd6f4; --accent2:#89b4fa; }

OS/plugin segments keep their brand colors; the theme controls the background, text, prompt accent, output colors, and the dir/git segments.

Icons load on demand

Built-in logos are real brand icons vendored into the package (no runtime dependency on a third-party repo) and loaded lazily, tinted to the segment color via CSS mask — so the script stays ~11 KB and a logo is fetched only when used. The base resolves next to wherever you load x-zsh; override with XZsh.iconBase. Logos: Simple Icons (CC0) + a couple from devicon (MIT).

Versions & custom plugins

Pin any plugin's version inline with name@version, and register your own segments — point at a Simple Icons slug, any SVG url, or fall back to an emoji/text icon:

<x-zsh plugins="node@22.3.0, go@1.23, k8s@staging"> … </x-zsh>

// register before the element scrolls into view (e.g. in <head>)
XZsh.plugin('acme', { slug: 'docker', txt: 'v2', bg: '#5b21b6', fg: '#fff' });
XZsh.plugin('beta', { url: 'https://…/logo.svg', bg: '#222', fg: '#fff' });
XZsh.os('myos', { name: 'MyOS', slug: 'archlinux', bg: '#222', fg: '#fff' });

Custom tag

import 'x-zsh';
// also expose it under your own hyphenated name
XZsh.register('acme-term');