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.
Look at the link before you change anything
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. 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.
Wikilinks and standard links behave differently
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:
- Pick one note with a broken image and one with a broken link.
- Find the path in each and walk it in Finder.
- Fix the path, or move the file to where the path expects it. For example, if
Trip.mdmoved intoArchive/and itsimages/folder stayed where it was,becomes. That assumes your app reads a path from the note’s own folder, as relative paths usually work. - 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.