0 Fork 0

mirror of https://github.com/narrrl/narl-workspace.git synced 2026-11-03 16:41:27 +01:00

Files

T

nvrl 4eb663e2d7 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.

2026-10-21 12:07:32 +02:00

3.1 KiB

Raw Blame History

Getting started

Run it

You need Rust (1.96 or newer) and bun to build it. The result is one binary with the whole frontend inside, so the machine it runs on needs neither.

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:

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. Every other setting has a default that works on your own machine. Configuration lists them all.

Log in

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

Press 2 to go to work.
Press o. A new document opens in the editor, in insert mode. Write something.
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.
Type :q to close it. It is in the list now, under today's date.
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.
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.
Press T. That is today's diary entry, started for you.
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 guide goes through a whole day with the workspace and explains each part as it comes up.

3.1 KiB Raw Blame History