mirror of
https://github.com/narrrl/narl-workspace.git
synced 2026-11-04 00:47:01 +01:00
nvrl
4eb663e2d7
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.
34 lines
1.5 KiB
Markdown
34 lines
1.5 KiB
Markdown
# Sharing
|
|
|
|
Any document can be shared read-only behind a link that cannot be guessed. The
|
|
reader needs no account.
|
|
|
|
| key or command | what it does |
|
|
| --- | --- |
|
|
| `s`, `:share` | share the document and copy its link; on a shared one, `s` asks before taking it back |
|
|
| `y`, `:link` | make a new link for the same document; the old one stops working |
|
|
| `:unshare` | stop sharing |
|
|
|
|
The link looks like `https://your-host/s/<token>#<key>`. The page renders the
|
|
document read-only and serves only the pictures and videos it embeds right now:
|
|
take a picture out of the document and it is gone from the link too. Links to
|
|
other documents in it are turned into plain text, since the reader could not
|
|
follow them. Sealed files are never shown; `:share` says how many the document
|
|
holds.
|
|
|
|
## Why the link has two halves
|
|
|
|
The token names the document; the key proves the reader was given the whole
|
|
link. A browser never sends the part after `#` to the server, so the key stays
|
|
out of access logs, referrers and link previews. A crawler or chat client that
|
|
kept only the path holds a link that answers `404`.
|
|
|
|
The server keeps only a SHA-256 of the key and compares it in constant time, and
|
|
a wrong key is answered exactly like an unknown token. That also means the full
|
|
link exists only once, when `:share` copies it. It cannot be read back from the
|
|
document later; `:link` makes a new one instead, which is also the way to cut a
|
|
reader off without unpublishing.
|
|
|
|
A document in the trash answers like an unknown link, and works again with the
|
|
same link when it is restored.
|