mirror of
https://github.com/narrrl/narl-workspace.git
synced 2026-11-03 16:41:27 +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.
105 lines
4.1 KiB
Markdown
105 lines
4.1 KiB
Markdown
# Writing
|
|
|
|
## The editor
|
|
|
|
`i` or `a` on an open document edits it. The editor is CodeMirror 6 with the
|
|
vim keymap: motions, operators, text objects, visual mode, registers, macros
|
|
and `.` all work, and `:w`, `:wq` and `:q!` do what they do in vim.
|
|
|
|
|
|
|
|
- `:name` on its own moves up into the title; `Enter`, `Esc` or `↓` goes back
|
|
down into the text. `:name <text>` renames without leaving the text.
|
|
- `]]`, `[[` and `gO` walk the headings, the same as in the reader.
|
|
- `gf` follows the link under the cursor, saving first, and `gx` opens it in
|
|
a new browser tab.
|
|
- `Ctrl-S` saves from anywhere, and `?` shows the help.
|
|
- Yanks and deletes go to the system clipboard too. `:set noclipboard` keeps
|
|
them in vim's registers only.
|
|
- `:set novim` turns the vim keys off for a plain editor; `:set vim` turns them
|
|
back on. On a touch screen they start off.
|
|
|
|
Drag, drop or paste an image, a video or a sound file into the text and it is
|
|
uploaded and embedded where the cursor is. `:upload` picks files to embed, and
|
|
`:media` lists every upload: `Enter` embeds the one under the cursor, `y`
|
|
copies its address.
|
|
|
|
## Saving
|
|
|
|
There is nothing to remember. Each change goes to the browser's storage as it is
|
|
typed, and to the server a couple of seconds after typing stops.
|
|
|
|
- When the server cannot be reached, the draft stays in the browser and the
|
|
save is tried again, less often the longer it fails, and at once when the
|
|
browser says it is back online.
|
|
- When a session runs out in the middle of a sentence, the login appears, and
|
|
logging in again carries on where it stopped, draft and all.
|
|
- When a tab dies in the middle of a document, opening the document again
|
|
restores the draft and says so. `:e!` throws the draft away.
|
|
- When the document was saved somewhere else since you opened it (another tab,
|
|
the phone, the SFTP mount), `:w` says so instead of overwriting it. `:e!`
|
|
takes the other version, and `:w!` writes yours anyway.
|
|
|
|
Each save keeps the text it replaces, so nothing written is lost. See
|
|
[Not losing things](Not-Losing-Things.md#history).
|
|
|
|
## Markdown
|
|
|
|
Documents are GitHub-flavoured markdown: headings, lists, task lists, tables,
|
|
quotes, code blocks and links. A single line break is kept as a line break.
|
|
|
|
Math is set by KaTeX:
|
|
|
|
- `$x^2$` inline;
|
|
- `$$ … $$` on lines of its own, or a ` ```math ` block, for a display formula.
|
|
|
|
|
|
|
|
## Links
|
|
|
|
A document links to another in two ways:
|
|
|
|
- by its address: `[the plan](/n/work/notes/plan)`;
|
|
- by its title: `[[Plan]]`, or `[[Plan|the plan]]` with a label of its own.
|
|
|
|
A title is looked for in the space the link is written in first, then in every
|
|
other. It matches a name in any case, or the slug of that name. Typing `[[` in
|
|
the editor offers the titles of documents as the search finds them. A title
|
|
that no document has yet is drawn dimmed, and following it offers to write that
|
|
document.
|
|
|
|
Links keep working when what they point at moves. Renaming a document, or a
|
|
folder above it, or moving either, rewrites the links to it in every document
|
|
that has one, in the same save: the path to the new one, a `[[title]]` to the
|
|
new name, the label left as it was. A link to something in the trash follows it
|
|
when it is restored; once it is deleted for good the link text stays and leads
|
|
nowhere.
|
|
|
|
`gb` or `:backlinks` lists the documents that link to the open one, each with
|
|
the line it does so on.
|
|
|
|
A link written inside a card, or a bare address in prose rather than a markdown
|
|
link, is not counted or rewritten.
|
|
|
|
## Templates
|
|
|
|
Any space can have a folder called `templates` at its root. Every document in
|
|
it is a template.
|
|
|
|
- `:new meeting` starts a document from `templates/meeting`. `Tab` completes the
|
|
template names.
|
|
- `:new meeting 2026-10-20 Budget` dates it and names it as well.
|
|
|
|
In a template these placeholders are filled in, on the clock of
|
|
`WORKSPACE_TIMEZONE` at the date the document is for:
|
|
|
|
| placeholder | becomes |
|
|
| --- | --- |
|
|
| `{{date}}` | `2026-10-20` |
|
|
| `{{weekday}}` | `Tuesday` |
|
|
| `{{time}}` | `14:05` |
|
|
| `{{title}}` | the new document's name |
|
|
|
|
A new diary entry starts from the diary's `templates/day` when there is one.
|
|
See [The diary](Diary.md).
|