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.

### 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.

## 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.

## 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 not encrypted

Note bodies are stored as plain text. **A note holding a password or an API key is
holding it in plain text in every backup you can download.** The mailbox
credentials, OAuth tokens and AI keys are sealed; note bodies are not, and neither
are task titles, descriptions or comments.

Encrypting them is on the list and is bigger than it sounds — the full-text index
and the folded search copy are both derived from the body, so both would have to go
and search would have to be rewritten. Until then: keep secrets somewhere built for
them.