aboutsummaryrefslogtreecommitdiffstats
path: root/docs/index.md
diff options
context:
space:
mode:
authoruser <user@clank>2026-08-15 23:53:30 +0200
committeruser <user@clank>2026-08-15 23:53:30 +0200
commit4dc055692c56324a94d1087331da8862ea650d2b (patch)
tree5ddec99f7cf6b144ede4138b6e952c84379725aa /docs/index.md
parentsl0ppty: marks a font actually draws at cell size (diff)
downloadslosh-4dc055692c56324a94d1087331da8862ea650d2b.tar.gz
slosh-4dc055692c56324a94d1087331da8862ea650d2b.tar.xz
slosh-4dc055692c56324a94d1087331da8862ea650d2b.zip
sl0ppty: a README you can read, and docs/ for the rest
The README was 331 lines and had become a manual with a title. Everything in it was true and most of it was the wrong thing to hand somebody who has just arrived: five pages of shader expression semantics before they have split a pane. So the front page is 60 lines -- what it is, install, run, where the docs are, and six bullets on what is actually different about it -- and the detail moved into docs/, nine pages that each answer one question: index.md what it is, install, run, where to go keys.md the leader, every default, rebinding, direct binds panes.md splitting, resizing, the mouse, dead panes, small terminals config.md the file, live reload, include, themes, the knobs shaders.md the passes, the built-ins, the expression language chrome.md where="chrome", channel, since, the perimeter trick layouts.md a session as a file, and writing one back out scripting.md the control socket, OSC 5577, headless design.md the two decisions, and a map of the source docs/nav holds the order and the grouping and nothing else -- titles come from each page's own heading, so a renamed page cannot end up with two names. It is what the site generator will read. Reference material that only existed in code comments is written down for the first time: every action that can be bound (including the two with no default key, which is what the palette is for), every control verb, the built-in shaders with what each takes, the pane-state ranking, and the layout file's shape. Two things I got wrong on the first pass and fixed before committing: the docs linked repo files through github.com URLs for a project whose remote is a private git server, so those are inline paths now; and the README advertised `make docs`, which does not exist yet. It will in the next commit, and it can be advertised then.
Diffstat (limited to 'docs/index.md')
-rw-r--r--docs/index.md67
1 files changed, 67 insertions, 0 deletions
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..69595a5
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,67 @@
+# sl0ppty
+
+A terminal multiplexer — panes, tabs, sessions you can detach from — written in
+C on top of [libghostty-vt](https://github.com/ghostty-org/ghostty).
+
+```
+╭──────────── nvim ─────────── ▬ □ ✕ ╮ ╭──────── npm run dev ──────── ▬ □ ✕ ╮
+│ │ │ │
+│ │ ╰────────────────────────────────────╯
+│ │ ╭──────────── shell ───────── ▬ □ ✕ ╮
+│ │ │ │
+╰─────────────────────────────────────╯ ╰────────────────────────────────────╯
+```
+
+## Install
+
+Needs [zig](https://ziglang.org) 0.16 and nothing else — no cmake, no
+autotools, no libraries. The result is one static binary.
+
+```bash
+make vendor # build the vendored terminal core (once, a couple of minutes)
+make # about a second
+make test # optional: the full suite, about eight seconds
+```
+
+## Run
+
+```bash
+sl0ppty # attach to session "main", creating it if needed
+sl0ppty -s work # a named session
+sl0ppty ls # what is running
+```
+
+Sessions keep running when you detach, or when your terminal or ssh connection
+goes away. Reattach with the same command.
+
+Then: `C-a \` to split, `C-a ?` for the cheatsheet, `C-a p` for every command
+by name.
+
+## Where to go
+
+- **[Keys](keys.md)** — the leader, the defaults, rebinding, the palette.
+- **[Panes and tabs](panes.md)** — splitting, moving, zooming, the mouse.
+- **[Configuration](config.md)** — one file, live reload, themes, `include`.
+- **[Shaders](shaders.md)** — colour passes over a pane's contents.
+- **[Chrome shaders](chrome.md)** — the same passes over a pane's frame.
+- **[Layouts](layouts.md)** — a session as a file you check in.
+- **[Scripting](scripting.md)** — the control socket, and what a pane can draw.
+- **[How it works](design.md)** — the two decisions that shape the rest.
+
+## Why another one
+
+The multiplexers we have are crusty, and the things that make them awkward are
+not features somebody forgot to add — they follow from how the programs are
+built. Layout state that is stored and edited rather than recomputed, so it
+drifts out of sync with itself. Mouse handling written as a second
+implementation of the drawing code, so the two disagree about where a button
+is. Extension models bolted onto a core that never expected one.
+
+So: start over, and stand on the shoulders of the person who already solved the
+genuinely hard part. The terminal emulation core from
+[ghostty](https://ghostty.org) is vendored as a library and does the VT
+parsing, scrollback, selection, images and key encoding. What sits on top is
+small, recomputes rather than remembers, and is scriptable to the same depth it
+is usable.
+
+About 10k lines of C, no dependencies beyond libc and the vendored core.