CoffeeLinking notes with [[wiki links]] without breaking them
Checked November 2026 against Obsidian's help on links. Coffee isn't affiliated with Obsidian.
A wiki link such as [[Trip plans]] points at a note by its name, so renaming the file leaves every link to it pointing at nothing. The way to avoid that is to use an app that rewrites links, and to be careful renaming in Finder when no such app is watching. If a link has already broken, you can repair it with a search and replace across the folder.
Two kinds of link
Markdown editors use two forms for linking one note to another:
| Compared | Wiki link | Markdown link |
|---|---|---|
| Looks like | [[Trip plans]] | [Trip plans](Trip%20plans.md) |
| Points at | A note's name, wherever it is | A file path, relative to this note |
| Breaks when | The note is renamed | The note is renamed or moved |
| Works elsewhere | Only in apps that support it | Any Markdown reader |
Wiki links are shorter to write and survive moving a note between folders. Markdown links are the portable form. Obsidian's help makes the same point: it generates wiki links by default for their compact format, and says that if interoperability is important, you can turn them off and use Markdown links instead. Spaces in a Markdown link's path need writing as %20.
Both have a few variations worth knowing. [[Trip plans|the trip]] shows different text. [[Trip plans#Hotels]] goes to a heading. Obsidian documents both, and Coffee reads both.
Renaming without breaking anything
Do it from inside your editor, as long as your editor rewrites links. Obsidian can update internal links automatically when you rename a file, and it can ask you first if you turn that off. Coffee does it too, as described below.
Renaming in Finder, in Terminal or from a script is what catches people out. The app may not be running, or may not be looking at that file, so nothing updates the links.
Repairing links by hand
You don't need any particular app for this. In Terminal, go to your notes folder and first see what would change:
grep -rl --include='*.md' '\[\[Old name[]|#]' .That lists each note with a link to Old name, including the forms with an alias or a heading. To rewrite them on a Mac:
find . -name '*.md' -exec sed -i '' -E 's/\[\[Old name(\]\]|\||#)/[[New name\1/g' {} +Back up the folder first, or commit it if it's in Git, because this edits files in place and has no undo. It's also a blunt tool that changes matching text inside code blocks too. And a name containing special characters such as . or ( needs escaping.
What Coffee rewrites
Coffee watches for a rename, waits until the title has stopped changing for 2 seconds, and then updates links across your library. That wait is there because editing the title heading of a note renames its file, and you don't want a rewrite for every pause in your typing.
These links are rewritten:
[[Note]][[Note|Alias]], keeping the alias[[Note#Heading]], keeping the heading[text](Note.md), a relative link, keeping the text and any heading
A message then says how many notes changed, with an Undo button for about 10 seconds. Undo only takes back notes that haven't changed since, so anything you've written in the meantime stays.
Coffee finds these links with the same parser its editor uses. That matters, because it means links shown inside code blocks and front matter, and image links, are never touched. A closed note is replaced in one atomic step, with its earlier text kept in version history. A note open in a window changes in its editor instead, so ⌘Z takes it back. If Coffee crashes or quits partway through, it finishes the job at the next launch.
What Coffee leaves alone
This list matters as much as the one above:
| Left alone | Why it matters |
|---|---|
| Private notes, locked or open | Links in them keep the old name, so update them yourself |
.txt files | Links inside them aren't rewritten |
Bare [[Old]] when another note still has that name | [[Old]] still means something, so it stays. A relative link to the renamed file is still updated |
Absolute paths and file: links | Not rewritten |
| Reference-style links | [text][ref] with [ref]: Note.md elsewhere isn't rewritten. Convert it first if it matters |
The #Heading part | A rename only changes the note's name. Renaming a section heading updates nothing that points to it |
A new name can also make a wiki link impossible to write. A title containing [, ], | or # can't go inside [[ ]], so those links stay as they are, and the message says how many links can't use the new name.
Renames in Finder
Be exact about this one, because it's the case people assume works.
A note open in Coffee, renamed in Finder: Coffee notices. It follows the note by its file identity and then updates links as usual.
A closed note, renamed in Finder: Coffee notices, as long as the file stays the same file, and then updates links as usual. It's the same if a script moves it, or if it happened while Coffee wasn't running, in which case the links change the next time the library opens. Moving a note to another folder in the library counts too, as does renaming the folder.
A closed note, replaced rather than renamed: a script that copies a note to a new name and deletes the old one makes a new file, so Coffee can't tell. A closed note renamed on another Mac and synced across may arrive this way too, and we haven't tested that.
An open note renamed on another Mac: when the sync arrives, it's a new file, so Coffee follows it only if the text is identical. Links are then updated.
If a link does break, the simplest repair is to rename the note back to the old name while Coffee is open, and rename it again. The commands above work too.
⌘-clicking a broken link creates a note. In Coffee, following [[Old]] when no note has that name makes a new note called Old, at the top of your library. That's how you make a new linked note on purpose. If you leave it without writing anything, it goes to the Trash, so a broken link doesn't leave an empty note behind.
Moving a note to another folder
A wiki link matches by name anywhere in the library, so it needs no change. Relative links pointing to the moved note are rewritten with the right path, as long as Coffee knows about the move.
The links inside the moved note are another matter. Moving a note doesn't rebase its own outgoing relative links, so [x](Other.md) in a note you've moved down a folder now points at the wrong place. Fix those by hand, or use wiki links in notes you expect to move around.
Seeing what links where
In Coffee, typing [[ offers matching note titles as you type, and at the end of each note a "Linked from" list shows the notes that link to it. It's kept out of the file itself, and you can turn it off in Settings. Private notes add nothing to this list. Coffee has no graph of your links. If you want one, Obsidian has that.
Questions
What is a wiki link?
It's a link written as [[Note name]], pointing at another note by its name instead of a file path. It isn't part of standard Markdown, so it only works in apps that support it.
Do wiki links break when you rename a note?
Yes, unless something rewrites them. Rename inside an app that updates links, such as Coffee or Obsidian, or repair them with a search and replace afterwards.
Does Coffee update links when I rename a note in Finder?
Yes, whether the note is open or closed, and even if Coffee wasn't running at the time, when it next opens that library. The one thing it can't follow is a note replaced by a new file under another name.
Should I use wiki links or Markdown links?
Use wiki links if your notes stay in apps that support them and you move notes around. Use Markdown links if other tools or people will read the files.
Does Coffee rewrite links in code blocks?
No. It finds links with its editor's parser, so code, front matter and images are left alone.