Move and rename Markdown files without breaking links or pictures

Checked November 2026 on macOS 26.

You decide your Pics folder should be called Images. You rename it in the Finder, open a note, and every picture is a broken icon. Nothing is lost: the pictures are all still there. But the notes still point at the old name.

Why it breaks

A Markdown note doesn't hold its pictures. It holds a line that says where each one is:

![](Pics/harbour.png)

That path is plain text. When the folder becomes Images, the file moves, and the text stays the same. Links to other notes work the same way, whether they're written [Day one](Trips/Day%20one.md) or [[Day one]].

The same happens when you move a note into a subfolder, if its links are relative to where it was. A link from Trips/Day one.md to ../Pics/map.png points somewhere else once the note is in Trips/Lisbon/.

Fixing it by hand

If the damage is done, a find and replace across your notes puts it right. Replace ](Pics/ with ](Images/, and [[Pics/ with [[Images/. Check the result before you save, because the same text might appear somewhere it shouldn't, such as in a code example. There's a guide to find and replace across Markdown files.

Two habits make this rarer:

  • Link by name, not by path. [[Day one]] keeps working wherever the note goes, as long as its name doesn't change and no other note has the same one. More in wiki links that don't break.
  • Decide on folders early. A folder for pictures beside your notes, named once, saves most of the trouble. See images in Markdown.

Letting the editor follow

Some editors change the links for you when you rename or move a file inside the app. Fewer notice a change made in the Finder, and that's where most folders get renamed.

Coffee follows both. When you rename or move a note in Coffee, rename a note or a picture in the Finder, or rename or move a folder in either, it changes the links to it in your other notes. After the folder becomes Images, the note says:

![](Images/harbour.png)

A line then says how many notes it updated, with Undo beside it.

What it follows:

  • [[links]] and Markdown links to a note you rename or move.
  • Links to pictures and other files when their folder is renamed or moved.
  • Links to a picture you rename in the Finder.
  • Links from notes inside a moved folder to things outside it.

It keeps the way each link was written, such as a size in ![[Pics/harbour.png|300]]. It never changes code or code blocks, so a path written as an example stays as you wrote it. Undo leaves alone any note you've changed since.

Moving notes in Coffee

You don't need the Finder to reorganise. Drag a note or a folder onto another folder in the sidebar, or onto All notes for the top of your library. Hold Option as you drop a note to copy it instead. Right-click a folder for New Folder and Rename…, or a note for Move to….

A moved note keeps its links, pictures, version history and comments. If a note of the same name is already there, the one you moved gets a name of its own, so nothing is replaced.

Questions

Why do my images break when I rename a folder?

The note stores the picture's path as text, and renaming the folder doesn't change that text. Either update the paths, or use an editor that updates them for you.

Do wiki links break when I move a note?

A link by name, like [[Day one]], keeps working when the note moves to another folder. It breaks when the note is renamed, unless your editor changes the links too.

Can I undo a rename that changed many notes?

In Coffee, yes: the notice after a change has Undo, and it puts the links back as they were in the notes you haven't touched since.

Does Coffee ever rename my files by itself?

No. Coffee changes the links inside your notes when you rename or move something. It doesn't move or rename your files unless you ask it to.