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.
3.0 KiB
Files and search
Files
A file is a node like a document, only with bytes instead of text. It sits in a
folder beside the notes about it, shows its size in the list, and Enter opens
it.
Put files in:
- drop them onto the list;
:uploadpicks files for the folder you are in;:importuploads a whole folder, and:import!a zip (see Not losing things);- copy them in over the SFTP mount.
Each upload is written to disk as it arrives, never held in memory, so the only
limit is WORKSPACE_MAX_UPLOAD_MB (1024 by default) per request.
What opens in place
- images, video and audio;
- PDFs, in the browser's own viewer;
- text and source code of any kind, with line numbers, up to the first 256 KiB;
- markdown, rendered, with
:sourceto see it as written; - CSV and TSV, as a table of the first 500 rows;
- certificates, keys and keystores (
.pem,.crt,.cer,.der,.csr,.key,.p8,.p12,.pfx), read on the server.
A certificate shows its subject, issuer, validity, key, names, usage and
fingerprints, and which key belongs to which certificate. A .p12 or an
encrypted key asks for its password, which opens it for that one look and is
not stored. Nothing of a private key is sent back but its algorithm and size.
Anything else is a download: :download (:dl) fetches the file under the
cursor, and gx opens it in a browser tab of its own. Files are renamed with
:name, moved like documents, and deleted into the trash with x.
Uploads are only ever served as types that cannot run in the browser. An HTML file or an SVG, for example, downloads instead of opening.
Search
| key | searches |
|---|---|
/ |
the space you are in |
Ctrl-P |
every space |
Results appear as you type, ranked by relevance, each with the space and
folder it is in. Tab or Ctrl-N / Ctrl-P walk them without leaving the
line, and Enter opens the one lit. Afterwards n and N open the next and
previous result beside the list, and :noh clears the search.
Each word you type matches the start of a word, so inge finds "ingest". All
the words must be there. Punctuation is ignored.
Inside files
A search reads the text files in the tree as well as the documents. A file
counts as text by its type, or when its first 8 KiB read as UTF-8 with no NUL
byte, which covers .log files and Makefiles. The first 256 KiB of each is
indexed, the same part the viewer shows. A file found by its text shows the
words around the match under its name.
The text is read when a file arrives, by upload, import or the SFTP mount, again when its bytes change, and at start for any file still missing it. PDFs, office documents and images are not read.
A sealed file is never indexed; see The vault. Sealing a file drops its text in the same step, and decrypting it reads it again.