docs: a guide, a wiki and screenshots

The README grew a section per feature and is a good reference, but nothing
said where to begin. docs/wiki now has a getting-started page, a guide that
walks through one day with the workspace and explains each part where it comes
up, and a page per part of the app, each with screenshots of what it
describes.

Three pages are read out of the code rather than written, so they cannot drift
from it: the keys and commands from Help.svelte and commands.ts, the same lists
`:help` draws; the settings from .env.example, which gains a heading for the
vault, trash and history settings so they no longer sit under mail; and the
API from the README's table. `make wiki` writes them, and `--check` fails when
one is stale or a link between pages leads nowhere. `--publish` lays the pages
out for a GitHub wiki: links without `.md`, images beside them, `[[` escaped so
the wiki does not take a command's help text for a link to a page.

The screenshots are taken by `make screenshots`: the debug binary on a
temporary data directory, with a password made up for the run, filled with an
example workspace over the API, and a headless Chromium driven over the
DevTools protocol through the views the docs show. Nothing outside the
temporary directory is touched but docs/images, and the pictures are cut to
256 colours, a third of their size, which a dark UI does not show.

The README opens with the banner, a CI badge, the guide, the features grouped
by what they are for, and six of the screenshots.
This commit is contained in:
nvrl committed 2026-10-21 12:07:32 +02:00
1 parent 7b2fd5579c
commit 4eb663e2d7
41 files changed
+2523 -25

No files matched your search

+88
View File
@@ -0,0 +1,88 @@
# Getting started
## Run it
You need Rust (1.96 or newer) and [bun](https://bun.sh) to build it. The result
is one binary with the whole frontend inside, so the machine it runs on needs
neither.
```sh
git clone https://github.com/narrrl/narl-workspace
cd narl-workspace
cp .env.example .env
```
Open `.env` and set three things:
- `WORKSPACE_USER`: the name you log in with.
- `WORKSPACE_PASSWORD`: the password. The server will not start while it is
still `change-me`.
- `WORKSPACE_SECRET`: 32 random characters that sign the login cookie. Make
one with `openssl rand -base64 32`.
Then build and start it:
```sh
make build
./target/release/narl-workspace
```
and open <http://127.0.0.1:4242>.
With Docker instead, `docker compose up -d --build` does the same; see
[Deploying](Deploying.md). Every other setting has a default that works on
your own machine. [Configuration](Configuration.md) lists them all.
## Log in
![The login](../images/login.png)
The workspace has one account, the one in `.env`. Wrong passwords are answered
more slowly each time. A browser that has logged in before is slowed only by
its own mistakes, so someone guessing from elsewhere cannot lock you out.
## Find your way around
A new workspace has three spaces: `diary`, `work` and `uni`. The bar along
the top shows them as numbered pills. `1`, `2` and `3` switch between them,
and `Tab` steps to the next one.
The screen has four parts:
- **the bar**, at the top: the spaces, where you are in the tree, how many
cards are late or due today, and the clock;
- **the list**, on the left: what is in the folder you are in;
- **the tiles**, on the right: the documents and files you have open;
- **the status line**, at the bottom: the mode you are in, and what the last
key or command did.
The rail of buttons on the right does the same as the keys, for a mouse.
## The first ten minutes
1. Press `2` to go to `work`.
2. Press `o`. A new document opens in the editor, in insert mode. Write
something.
3. Press `Esc` to leave insert mode, then type `:name Plans for the week` and
`Enter` to give it a name. There is no need to save: the document is saved
a couple of seconds after you stop typing. `:w` saves at once anyway.
4. Type `:q` to close it. It is in the list now, under today's date.
5. Press `O` (capital). The command line opens with `:mkdir ` already typed;
add a name and press `Enter`. `l` or `Enter` on the folder goes into it, and
`h` comes back up.
6. Press `c`, type `try the board`, and press `Enter`. That is a card in the
inbox of this space's board. Press `b` to see the board, and `b` again to go
back.
7. Press `T`. That is today's diary entry, started for you.
8. Press `?` for the list of every key and command, and `Esc` to close it.
On a phone the same things are buttons: the dock at the bottom has a new
document, a new folder, the board, today's entry, an upload and a search, and
the `⋯` on a row (or a long press on it) has what can be done to that row.
![The workspace on a phone](../images/mobile-tree.png)
## Next
[The guide](Guide.md) goes through a whole day with the workspace and
explains each part as it comes up.