When inserting an image in Markdown, write the route from the manuscript file to the image, not the image’s location in isolation. If manuscript/chapter01.md refers to assets/maps/port.png, the markup is . After moving either file, verify that the resolved path still reaches the intended image. A visible preview alone is not enough because an older file with the same name may be displayed by accident.
This article focuses on inserting one Markdown image and preserving that reference after a move. It does not cover image editing, copyright decisions, or the long-term availability of externally hosted images. A broader EPUB workflow for body images, covers, and deletion warnings belongs to a different article.
Resolve the path from the manuscript folder
The basic Markdown form is . Alternative text should briefly identify the content when the image cannot be seen. For a relative path, the practical starting point is the folder that contains the manuscript file.
Consider this layout:
book/manuscript/chapter01.mdbook/assets/maps/port.png
From chapter01.md, move up once from manuscript, then descend into assets/maps. The correct reference is therefore . Without ../, the editor would look for book/manuscript/assets/maps/port.png, which is a different location.
An absolute path may appear to work on your Mac, but the same directory will probably not exist when the book folder is copied to another computer. For assets kept inside a project, a relative route preserves the relationship between manuscript and image more reliably.
Check three facts immediately after insertion
After writing the markup, verify three separate facts:
port.pngexists in the intended folder.- Resolving the markup from the manuscript reaches that exact file.
- The alternative text says “Map of the harbor,” not merely “image.”
A preview can hide a wrong target when two folders contain files with the same name. As a temporary test, rename the intended image to port-check.png. The reference should break until the markup is changed. Restore the name after confirming the target.
Keep capitalization, spaces, and full-width or half-width characters consistent in file names. A Mac volume may make two spellings look interchangeable, while another environment or a publishing process treats them as different. Plan for Port.png and port.png to be distinct names.
Recalculate from the source when only the manuscript moves
Suppose chapter01.md moves to book/chapters/part1/chapter01.md, while the image remains at book/assets/maps/port.png. The manuscript must now move up two folders before entering assets/maps, so its new reference becomes ../../assets/maps/port.png.
Do not copy the image during a manuscript-only test. A second image creates an ambiguity about which file is authoritative. Keep the image fixed, place the old and new markup side by side, and read the entire folder route rather than checking only the final file name.
Count uses before moving only the image
Now keep the manuscript in its original folder and move the image from book/assets/maps/port.png to book/media/port.png. The new reference is ../media/port.png. Before the move, search for the old path and count its uses. One image may be referenced by several chapters, so fixing a single preview does not prove that every use is intact.
After the move, the old path should return zero active references. Count the new path and compare the results with the chapters that are supposed to use the image. A blind replace can also alter prose or a code example, so check each target line. Cross-file batch replacement is a separate task from image insertion and path reasoning.
Treat renaming and reference rewriting as two Rune Studio steps
In a hands-on check, renaming the image file alone did not update the Markdown references. Do not describe a move or rename as automatically rewriting every reference. After the file operation, decide separately whether the source notation should change.
Running the separate reference-rewrite function then updated two locations across two files. The controlled order is: rename the file, count the old references, review the target and proposed changes, run the rewrite, then search both old and new references. The file operation and source rewrite are not one automatic event.
Published documentation describes txt, text, md, and markdown source, source-relative paths containing ../, open tabs, and encoding preservation for closed manuscripts within the rewrite scope. External URLs, mailto: links, and page anchors are excluded. The observed result is limited to two files and two locations; it is not evidence of automatic repair for HTML, CSS, every Markdown dialect, or every move.
Diagnose a broken reference in a fixed order
When an image disappears, first locate the manuscript file. Second, resolve every path segment from that folder. Third, verify the image’s actual location and exact name. Starting with preview settings or image format can distract from a missing ../ segment.
After correcting the path, confirm that the old route no longer appears, the number of new references matches expectations, and you have not created an unnecessary duplicate image. That is the difference between “something appeared” and “this markup reaches the intended file.”
Treat copying and renaming as different from moving
Moving and copying an image do not have the same expected destination. A move requires existing references to reach the new location. A copy requires an editorial decision first: which chapters continue to use the original, and which chapters should point to the new copy. Not every reference should automatically switch to the duplicate.
Renaming also needs its own count. Before changing port.png to harbor-map.png, count every use. After the reference rewrite, the old name should have zero active uses and the new name should have the planned count. Renaming only the file breaks old markup; changing only the markup breaks when the file still has the old name.
On the reference sheet, separate the pre-operation manuscript, pre-operation image, and the image that becomes authoritative afterward. This distinction identifies which of two same-named copies may be removed. If the copied or renamed image contains different content, review its alternative text instead of carrying forward the old description.
Conclusion: test a source move and an image move separately
Create copies of chapter01.md and port.png, then insert . Move only the manuscript and recalculate from its new folder. Restore it, move only the image, and reconcile the old and new reference counts.
If you are considering Rune Studio, check the supported source types and rewrite exclusions on the Rune Studio product page. After a rename, run the separate reference-review and rewrite step, then search both old and new paths. The finish line is not a preview that happened to render once. It is a source path that resolves to one intended image after the operation.
