How to fix broken Markdown links and images after moving notes

Why links and images break when Markdown notes move, how to read the path in a link, and how to repair a copied folder one note at a time.

Updated by Thomas Sivilay. Compared as of .

A Markdown note is a text file, so a broken link is a line of text you can read. Open the note in a plain text editor and find the link. It will be one of three kinds.

  • A wikilink, [[Trip plan]] or ![[photo.png]]. It names a note or file and lets the app find it. Obsidian writes these by default.
  • A relative path, [Trip plan](Trip%20plan.md) or ![](images/photo.png). It points from the note’s own folder to the file.
  • A path from the vault root, like Projects/Trip plan.md. Obsidian’s help notes that folder paths in its links start at the vault root and use forward slashes.

Knowing which kind you have tells you why it broke and how to fix it.

Trace a relative path

A relative path is directions from where the note sits. images/photo.png means “the images folder next to this note, then photo.png”. ../images/photo.png means “up one folder first”.

So when a note moves, every relative path in it now starts from a new place. If the note moved and its images folder did not, the directions lead nowhere. Walk the path by hand in Finder, starting from the note’s folder, and you will see where it breaks.

Two details catch people out. A space in a standard Markdown link has to be written as %20, or the whole destination wrapped in angle brackets, <images/my photo.png>. And a name has to match exactly, including the extension.

Move notes and their files together

The simplest fix is to not separate them. Move a note together with the folder its images live in, and relative paths keep working, because the directions from the note to the image have not changed.

Exports are the usual cause. An export can put images next to each note, in one shared folder, or inside a bundle per note, like TextBundle. If you reorganize afterwards, move each note with what it points to, or move everything at once and keep the folder layout.

A bare wikilink, [[Trip plan]], finds its target by name, so it keeps working after a move as long as that name is unique. A wikilink with a folder in it, [[Projects/Trip plan]], breaks when the target moves out of that folder. Either kind breaks on a rename, unless the app updates the link, or when the app reading the note does not use wikilinks.

A standard link points at a path, so it survives a rename only if you edit it, but every Markdown app understands it. Obsidian can switch between the two: under Files and links, turn off Use [[Wikilinks]] and it writes standard Markdown links instead. Obsidian can also update internal links automatically when you rename a file, which helps only while the vault is open in Obsidian.

Raven reads [[wiki-style]] links and shows backlinks for the note you are reading. Images you add in Raven go into a managed folder in the vault.

Repair one copied note first

Work on a copy of the folder, never the original. Then:

  1. Pick one note with a broken image and one with a broken link.
  2. Find the path in each and walk it in Finder.
  3. Fix the path, or move the file to where the path expects it. For example, if Trip.md moved into Archive/ and its images/ folder stayed where it was, ![](images/photo.png) becomes ![](../images/photo.png). That assumes your app reads a path from the note’s own folder, as relative paths usually work.
  4. Open the note in your Markdown app and check it.

Once one note works, you know the pattern, and you can apply it to the rest with a search across the folder. Plain files make that search easy in Finder, a terminal, or any editor.

Check the folder in a second app

When the copy looks right, open the same folder in a second Markdown app. Every note in Raven is a real .md file in a folder you own, so you can open those files in Finder, terminal tools, git, or another editor as well.

If a note reads the same in both, the links are written in a way more than one app understands. That is the best sign a folder will survive the next move too. If you are moving from Bear, the Bear export guide lists the notes worth checking first. If you are moving from Obsidian, see what to check when moving a vault.

questions

Straight answers.

Why did my images break after I moved a note?

Most often the image link is a path relative to the note, like images/photo.png. Move the note without its images folder and the path points at nothing. Move them together, or edit the path.

What is the difference between [[Note]] and [Note](Note.md)?

The first is a wikilink, which finds a note by name. The second is a standard Markdown link, which points at a file path. Obsidian writes wikilinks by default; a standard link is what most other Markdown apps expect.

Does Raven read wikilinks?

Yes. Raven reads [[wiki-style]] links and shows backlinks for the note you're reading.

keep reading

Beautiful notes. Never locked in.

Native on Mac, iPhone, and iPad, saved as plain Markdown files you control.

Download Raven