Manage Relative Image and Link Paths in Markdown

When an image disappears from a Markdown preview after you reorganize a project, the image may still exist; the manuscript may simply contain an old relative path. The practical fix is to separate image references from document links, calculate each route from its source file, and accept the move only when the old path has zero matches and every expected new path is present.

See the move from the chapter’s position

Consider this compact project:

book/
├── chapters/C1.md
├── chapters/C2.md
├── chapters/C3.md
├── images/I1.png
├── images/I2.png
├── images/I3.png
└── refs/source-note.md

From chapters/C1.md, the image reference ![Figure 1](../images/I1.png) goes up to book and then down into images. If I1.png moves to assets/I1.png, the new reference is ![Figure 1](../assets/I1.png). A document link such as [source note](../refs/source-note.md) does not change because the note did not move.

That distinction matters. A broad replacement of every relative link can damage references that were already correct.

Account for chapters stored at different depths

The number of ../ segments comes from the source file’s depth. These are calculation examples:

Only the first row reflects the move performed in the recorded run. The deeper chapter rows show how to calculate paths; they are not observed results from that run.

Use two searches, not one

Before moving an asset, find every occurrence of its old path. After the move, search twice:

1. The old path must return zero matches.
2. The new path must return the same number of references you expected to preserve.

Zero old matches alone can mean the links were deleted. Three new matches alone can coexist with a fourth stale reference elsewhere. For a project that also contains two document links, search the unchanged refs paths and confirm their count did not move with the images.

Where Rune Studio helps—and where you still check

Rune Studio’s current Mac documentation describes path rewriting for Markdown images and links when files or folders are moved or renamed. In the run used for this article, images/I1.png had three occurrences in one file. The image was moved to assets/I1.png, three references in C1.md were rewritten, and the final search returned zero old paths and three new paths.

The move and rewrite appear as separate recorded actions. That result does not prove that every move made through Finder, every operating-system alias, or every location outside the workspace is tracked without intervention. Test the exact move method you plan to use on a duplicate project, then perform the old/new search yourself. Cloud synchronization and collaborative editing are outside this result.

Keep the route, not the folder name, in mind

Relative-path management is easier when you ask, “How does this chapter reach that file?” Move only the references whose target moved, preserve unrelated document links, and finish with zero stale paths plus the full expected new count.

The current Mac app’s manuscript and asset workflow is described on the Rune Studio website.