Notezbeta
Back to blog

Links that survive a rename

ProductivityDenis Povarov

Everyone who has kept a linked archive for more than a year has met this bug.

You wrote a note called Q3 planning. Over eight months, thirty other notes came to reference it. Then Q3 ended, and you renamed it Q3 planning (2025) — the obviously correct thing to do.

Thirty links broke. Not loudly. They still render, still look like links, and now point at a note that does not exist. Some systems helpfully offer to create it for you, so you end up with a second empty Q3 planning note haunting your graph.

The cause is that most wiki-style note apps store the link as the title. [[Q3 planning]] is literally the string "Q3 planning", resolved at render time by searching for a note with that name. The link is a guess that happens to be right most of the time.

Notez stores the id.

What [[ actually inserts

Type [[ in the editor and a picker opens over the notes in your workspace. Pick one — or create a new note right from the picker — and what lands in the document is a node holding two things:

  • noteId — the target note's actual identifier

  • fallbackTitle — the title at the moment you inserted it

The id is the link. The fallback title is a caption of last resort.

When the chip renders, it looks up the target note by id and shows its current title. Rename the target and every chip pointing at it updates, everywhere, immediately. Nothing to repair, no bulk find-and-replace across your archive, no "unresolved links" report to work through on a Sunday.

This also means links are unambiguous in a way title links can never be. Two notes can share a title. Two notes cannot share an id.

Because links are stored as real references, the reverse direction is free.

Every time a note is saved, Notez walks the saved document, collects the note ids it references, and reconciles that set against what it had recorded before — inserting the new links, deleting the removed ones. The link table is a pure function of your content. It cannot drift out of sync with what you actually wrote, because it is rebuilt from what you actually wrote on every save.

A few things get filtered out during that pass, each for a concrete reason:

  • Self-links. A note referencing itself is not a relationship.

  • Cross-workspace targets. Only notes in the same workspace are kept. This is why a link from your work workspace can never leak the existence of a personal note — not by policy, but by construction.

  • Malformed ids. Notes coming from an importer can carry unresolved placeholder references before the import finishes wiring them up. Those are dropped rather than allowed to blow up the save.

Backlinks are then simply the same table read the other way: every note whose content references this one. There is no separate backlink index to rebuild and no maintenance mode. The Linked notes section on a note shows both directions.

Inline [[ links are not the only way notes point at each other. The relation custom property is the other one — a typed field on a note whose value is another note. A Client property on every meeting note, pointing at that client's note.

They look similar and they are stored completely differently. Inline links are written into the link table on save. Relation links are derived at read time and never written there.

The reason is a bug we would rather not ship twice. The save-time reconciliation diffs the entire set of links for a note and deletes anything not present in the content. If relation-property links were merged into that same table, the next content save on that note would look at the document, not find them, and delete them. Your Client relations would evaporate one note at a time, at exactly the moment the note was edited — which is to say, invisibly and only to your most active notes.

So the two kinds live in separate storage and are unioned when you read them. Slightly more work per read; no possibility of one silently eating the other.

The practical difference for you:

  • Inline links are prose. They belong mid-sentence, where the connection is a thought you are having: "this follows from [[the retry postmortem]]".

  • Relation properties are structure. They belong when every note of a kind has this same pointer, and you want to filter and sort by it.

Use both. They answer different questions.

The graph

Once links are real references, a graph view is a rendering of data you already have rather than a separate thing to build. Any note's Linked notes section can be viewed as a list or as a graph of what it connects to and what connects back.

A caveat worth stating: a graph view is genuinely useful for local exploration — seeing the neighbourhood around one note, noticing a cluster you did not plan. It is much less useful as a whole-archive visualization. Ten thousand notes rendered as a hairball is a screensaver. We built the local one.

Share a note publicly and its inline links behave carefully. The public view has no access to your workspace, so a chip renders the fallbackTitle captured at insertion time — the caption of last resort finally earning its keep — and only becomes a working link if the target note is also publicly shared.

If it is not shared, the chip renders as inert, greyed-out text. It tells the reader something is referenced there without leaking its current title or letting them at it.

This is the correct default, and it is worth knowing before you share a note: a shared note does not drag its linked notes into public view with it. If you want a linked set to be readable, you share each note in it.

A practical way to use this

Linking is one of those features that is easy to over-plan and then never use. What actually works:

  1. Link while writing, not afterward. The moment you type a phrase that refers to something you already wrote is the moment you know the link exists. Later, you will not remember.

  2. Do not link everything. A note linked from forty places tells you nothing. Links are only signal when they are selective.

  3. Check backlinks before you write a new note. Open the note on the subject, look at what already points at it, and you will often find you wrote most of the new note eight months ago.

  4. Promote a repeated link to a relation property. If you have linked to a client's note from every meeting note by hand, that is not prose any more — it is a field. Make it one, and get filtering and sorting for free.

  5. Rename freely. This is the whole point. Titles are descriptions, not identifiers, and you should be able to improve them whenever a better one occurs to you.

That last one is the quiet benefit of id-based links, and it takes a while to notice. In a title-linked system you gradually stop renaming things, because renaming has a cost and you have been burned. You end up with an archive full of titles you settled for.

Links that survive a rename mean the titles keep getting better.

Continue reading