aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
authoruser <user@clank>2026-08-16 00:00:45 +0200
committeruser <user@clank>2026-08-16 00:00:45 +0200
commit910d47dc4ae10fb3c388f6883e5107d9659fa727 (patch)
treeaaea5134d0e0b5e66cfca4fefd301ddd72b08a18 /README.md
parentsl0ppty: a README you can read, and docs/ for the rest (diff)
downloadslosh-910d47dc4ae10fb3c388f6883e5107d9659fa727.tar.gz
slosh-910d47dc4ae10fb3c388f6883e5107d9659fa727.tar.xz
slosh-910d47dc4ae10fb3c388f6883e5107d9659fa727.zip
sl0ppty: make docs
contrib/gen-docs renders docs/ into a static site: one file of stdlib Python and one stylesheet, no toolchain, no package manager, no npm. Same argument as src/kdl.c being a hand-rolled KDL subset rather than a library -- the input is ours, we know exactly which constructs it uses, and a docs build that needs a lockfile is a docs build nobody runs. What the Markdown subset understands is what docs/ actually contains: headings (with anchors), paragraphs, fenced code, pipe tables, lists one level deep, blockquotes, rules, `code`, bold, italic, links. Anything else is escaped and passed through as text. A construct nobody uses is not supported on purpose: it would be untested code pretending to be a feature. The layout is a sidebar of sections from docs/nav, the page, and its own headings down the right; prev/next chains the nav order; a link to another page is rewritten to its rendered page, so the same Markdown reads correctly on a forge and on the site. The colours are the session's own default theme, so the docs look like the thing they document, and the light variant follows the reader's system preference rather than a toggle nobody would find. Zero JavaScript -- the narrow-screen menu is a checkbox. Two things came out of looking at it in a browser rather than trusting the HTML. The hero diagram was hand-drawn and its lines were 78 and 79 columns long, which is visible. It is generated from a real session now -- three panes, a layout file, a text snapshot -- so it is exactly what the program draws. Terminal art also needs tighter leading and a font whose box drawing joins, so a fence with box characters in it and no language is emitted as art rather than code and styled for that. Detected rather than declared, because the alternative is a marker on every fence and one of them getting forgotten. (Vertical rules still break between lines in a browser: the glyph does not fill its em box, and no amount of CSS changes that. Widths line up, which is the part that matters.) The narrow-screen menu opened over a page that showed through underneath it: as a grid child taken out of flow it kept its content height, so `bottom: 0` did nothing. It has an explicit height now. tests/test_docs.py checks both jobs. The site: every page in the nav is rendered, carries the whole sidebar, is marked as current on its own page, chains prev/next, and no internal link in the output points at a file that is not there. The subset: each construct, and the one that matters most -- markup inside a code span is not markup, because half of these docs are shader expressions full of asterisks. A page missing from docs/nav fails the build, and so does a nav entry with no file: an unreachable page whose only symptom is its absence is the failure mode a hand-written nav has.
Diffstat (limited to 'README.md')
-rw-r--r--README.md22
1 files changed, 16 insertions, 6 deletions
diff --git a/README.md b/README.md
index 889a0db..1c3c291 100644
--- a/README.md
+++ b/README.md
@@ -4,12 +4,19 @@ A terminal multiplexer — panes, tabs, sessions you can detach from — written
C on top of [libghostty-vt](https://github.com/ghostty-org/ghostty).
```
-╭──────────── nvim ─────────── ▬ □ ✕ ╮ ╭──────── npm run dev ──────── ▬ □ ✕ ╮
-│ │ │ │
-│ │ ╰────────────────────────────────────╯
-│ │ ╭──────────── shell ───────── ▬ □ ✕ ╮
-│ │ │ │
-╰─────────────────────────────────────╯ ╰────────────────────────────────────╯
+╭────────── nvim ─────────── ▬ □ ✕ ╮ ╭─────── npm run dev ─────── ▬ □ ✕ ╮
+│ │ │ │
+│ │ │ │
+│ │ │ │
+│ │ │ │
+│ │ ╰──────────────────────────────────╯
+│ │
+│ │ ╭────────── shell ────────── ▬ □ ✕ ╮
+│ │ │ │
+│ │ │ │
+│ │ │ │
+│ │ │ │
+╰──────────────────────────────────╯ ╰──────────────────────────────────╯
```
## Install
@@ -41,6 +48,9 @@ split, `C-a ?` for the keys, `C-a p` for every command by name.
[layouts](docs/layouts.md) · [scripting](docs/scripting.md) ·
[how it works](docs/design.md)
+`make docs` renders the same pages as a static site into `build/docs` — no
+dependencies, one file of Python and one stylesheet.
+
## What is different about it
- **The mouse works properly.** Click a border to split toward it, drag a gap to