verdande/docs/notes.md

# Notes

Markdown in, Markdown out. Nothing in between.

A note is written as rich text — headings, lists, quotations, code — and stored as
the Markdown it looks like. That is not a detail about the database: it is what
makes a note yours. Export gives you the same text you were looking at, and on the
day this program is gone, every note opens in any editor.

## Writing

Start typing. **The first line is the title** — always, and re-derived every time
you save, so a note you rewrite the top of is called by what it now says rather
than by what it once did.

| Style | Written as | Shortcut |
|---|---|---|
| Title | `# ` at the start of the line | pick it in **Aa** |
| Heading | `## ` | |
| Subheading | `### ` | |
| Quote | `> ` | |
| Code block | three backticks, with an optional language | |
| Bullet and numbered lists | `- ` and `1. `, nested with Tab | |
| Bold | two asterisks around the words | ⌘B |
| Italic | one asterisk around the words | ⌘I |
| Underline | a `u` tag around the words | ⌘U |
| Strikethrough | two tildes around the words | |
| Code | one backtick around the words | |

Every line becomes exactly one block. Markdown would normally join consecutive
lines into a paragraph; here it does not, because you typed a line and expect to
get it back.

Press the source button in the toolbar to see the note as the file it is. Edits there are edits to the
note.

### Pictures

Paste one, or drag it onto the note. It is stored with the note and travels with
it in an export. Every raster format works; SVG is stored but not shown inline —
it is a document that can run script, and a note is not a place to run somebody
else's.

**Click one to see it whole.** In the note it is scaled down to the width of the
column — a photo off a phone is four thousand pixels across — so what you are
looking at is a thumbnail that does not look like one. The full-size view has a
button that copies the picture to the clipboard, and a link that opens it in its
own tab. Escape closes it and puts the cursor back where it was.

Copying converts to PNG on the way out when it has to. Clipboards take PNG and
little else, and a photo off a phone is a JPEG — without the conversion the copy
either fails or succeeds with something nothing will paste.

### Code blocks

A fenced block is coloured for the language it names, and guesses when it does not.
Each one carries a **Copy** button in its corner.

## Linking

Three kinds of reference, parsed out of the text as you write it:

| You type | It means |
|---|---|
| `#Firma` | The project — the same `#Firma` quick add understands, not a second kind of tag |
| `[[Møde med Anders]]` | Another note, by its title |
| A pasted task link | That task |

Links are an index over the text, rebuilt every time the note is saved. The text
stays the truth.

**The interesting direction is backwards.** A task shows what has been written
about it, and a project shows the notes filed in it — without anybody having to
remember to attach anything. Write `#Firma` in a note and it appears on that
project's page.

A link to something that has been deleted reads as a dead link. It is a fact about
the note, and it should not vanish because something it mentioned did.

## Filing and sharing

A note belongs to a project, or to nobody.

- **In a project:** everybody who can read the project can read the note, and an
  editor can change it. Choose it under **Share in** at the foot of the note.
- **In no project:** yours, and nobody else's.

There is no folder tree. Projects, groups and labels already exist, are already
shared and already have roles — a second hierarchy to file things in is one too
many, and a note in a project inherits every one of those answers.

### Sharing one note with one person

Filing a note in a project is the right tool when the note belongs with a body of
work, and the wrong one when it is just *let Sofie see this*. **Del med personer**
at the foot of the note does the second: this note, this person, as reader or
editor. Only the note's owner can share it.

Type an **email address** rather than picking a name, and one of two things
happens. An address that already has an account is shared with straight away. One
that does not gets an invitation — a link that creates the account and the share
together, so the note is theirs the moment they sign up. Invitations wait in the
panel under the note, where they can be withdrawn; that is the only way back, since
only the token's hash is stored and a link sent to the wrong address cannot be
looked up.

### Naming somebody in a note

Writing `@Sofie` in a note shares it with her and tells her. Naming somebody in a
note *is* wanting them to read it, and doing it as two acts — write the name, then
open the panel and find the person — meant the second was forgotten, and the note
sat there addressing somebody who could not see it. The editor suggests names after
`@`, the same way `#` suggests projects.

- **Only the owner's mentions share.** An editor may write the name; giving
  somebody else's note away is the owner's alone.
- **As a reader**, which is the least that satisfies "look at this". A role you
  have raised in the panel is never lowered by a mention.
- **Only a name that has just appeared** counts. A note is saved on every typing
  pause, so without that every save would be another share and another notification
  about the same name.

## Finding

The list groups itself: favourites first, then **Today**, **Yesterday**, **This
week**, and then by month. Sort by created, last touched or name, and the grouping
follows — sorted by name it groups by first letter instead.

Search finds a word wherever it is:

- **`gron` finds `grøn`.** Unicode does not consider `ø` an accented `o`, so
  stripping diacritics is not enough for Danish. A folded copy of every note is
  indexed beside the original.
- **`inventory` finds `keepInventory`.** An index is built of whole words, and a
  decade of notes is full of commands and identifiers that are several words in
  one. When the index has nothing, the text itself is read.
- Results are ranked by how well they match, with the title weighted ten times the
  body. A word in the title is what the note is about; the same word once in a long
  body is a mention.

Two places to search from, and they now agree. The field above the list filters it
in place. **⌘K** searches everything at once — tasks, projects, notes and the
settings — and picking a note from it opens that note *with the rest of the matches
still in the list beside it*. It used to drop you on the ordinary list, so the
other results existed only in the popup you had just closed. The address carries
the search, which also means a search worth keeping can be bookmarked or sent to
somebody.

## Putting notes away

Two different things, and the difference matters:

- **Archive** — this is finished and I do not want to read past it. It stays
  findable and comes back whenever you ask.
- **Trash** — this was a mistake. It is gone in thirty days.

Select several with ⌘-click and shift-click to archive or delete them together.

## In and out

**Export** gives you a zip of Markdown files, one per note, with the dates in a
YAML front matter block that Obsidian and Bear also read:

```markdown
---
created: 2019-04-02T10:15:00Z
modified: 2024-11-30T21:04:00Z
---

# Møde med Anders

Han vil gerne have kaffe hver uge.
```

**Import** takes the same shape back. Pictures travel in the zip beside the notes,
and the links in the text are relative — so a note and its pictures must be in the
same archive, which matters when a large export is split into parts.

Two things to know before importing:

- **Nothing is merged.** Every run creates new notes. Importing the same archive
  twice gives you two of everything.
- **The dates are read from the front matter.** Without them, a move of a thousand
  notes is a pile that was all written the same evening — and the order they were
  written in is half of what an archive is.

### From Apple Notes

`tools/apple-notes-til-markdown.py` in the repository exports Apple Notes to
exactly this shape, front matter and pictures included. It is macOS-only, because
Apple Notes is.

For a large library, `tools/pak-noter-i-portioner.py` splits the export into
uploadable parts, keeping each note with its own pictures.

## What is encrypted, and what is not

**A note's title and body are sealed** in the database, under a key kept in a file
beside it rather than inside it. A backup you download does not carry the key, so
it does not carry your notes.

Both halves, not only the body: a note's title is its first line, so a readable
title beside a sealed body would leave the beginning of every note in the open.

**What is still in the clear:** task titles, descriptions and comments — and the
list of what a note links to, so a stolen file shows which projects and tasks a
note points at, though not what it says.

Sealing the notes cost the search its index — a full-text index over a note's body
is another copy of that body — so search reads the notes themselves now. At twelve
hundred notes that is about forty milliseconds, and the box waits a quarter of a
second after you stop typing, so you will not see it.