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.
1.5 KiB
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.