Open two links to the same file after you move its containing folder. Try one written with a short name and one with a folder path. Check that both links open the intended file, especially if a note elsewhere has the same name.
Obsidian's link settings can update internal links when you rename a vault file. Test the actual operation you use for a folder move, especially if you expect Finder, Explorer or a sync client to make the change. Work in a disposable copy of the vault so you can restore the same starting paths for each run.
Make a reference set you can inspect
Create a project folder inside a test vault and a notes folder outside that project folder. Add a short “Brief” note to the project and an image in a subfolder. In the outside note, link to the brief and embed the image. In the brief, link back to the outside note. Then add another note with the same file name under a third folder. That exposes links losing their intended destination when they depend on an unqualified name.
Record where the links land before changing anything. Open the brief from each side and check the attachment in the rendered note. Save a list of expected targets. Save a plain copy of the vault before the moves so you can compare the text of changed links.
Run each move from a fresh copy
Rename or move the project folder inside Obsidian with your chosen link-update setting. Open each link again and note which raw link destinations changed. Restore the baseline, then repeat with your file manager and the app in the state you normally use. A file-system move may appear differently depending on which changes the app observes. Treat any resolved link that points to the same-named note as a failure.
For the attachment test, place the outside note and image in different layers of the folder tree. A move that preserves an adjacent file link can still break a path from outside the project. Check both reference directions in the same run.
The CommonMark specification specifies how a Markdown link destination is written, while Obsidian also has wikilinks. If the vault must work in another reader, try the moves with a relative Markdown link and open the result there too. For a real migration, work folder by folder, record the new paths, and search for old path prefixes before removing the backup.
Set up the vault so a wrong link is easy to see
Use three folders in the test copy. Under Projects, add Lantern and put a note there called Brief. Put a second Brief inside an Archive folder. Add a short sentence to each that states which note it is. A title alone has almost no value in this test since the titles match. In the notes folder, create a separate check page and link to the Lantern brief. Use one link generated by your usual editor, and one that refers to the path explicitly.
Before moving the folder, click every reference and record the file it opens. For the short link, observe which note the app chooses today. If it already goes to the archived brief, adjust the test to include one resolved reference with an explicit path and one ambiguous reference. Your test covers two independent outcomes. First, a previously working link should keep reaching its original target. Second, when a short link is already ambiguous, the move gives you an opportunity to make it explicit.
Include an attachment under the project folder and embed the file in the outside check page. Give the attachment easily identifiable contents. When you move the whole folder, the relationship of internal files to each other stays the same, but the path from an outside note may change. Keep a link from the moved brief back to the outside check page to see which references break in each direction.
Read the original and updated link text
Open the check page in source view and copy the original references to a small test log. Note whether each uses a wiki link or Markdown link and whether it points to a heading within the file. Then rename the project folder with link updates enabled and compare the new references. A heading link should still reach the intended section, even if the file path still opens. The reverse can happen as well. A short link in the app can still find a file after a move while its original wording is unusable in a different viewer.
| What you see | What to check next |
|---|---|
| Both Brief links open the archived project | The link text may be ambiguous. Use an explicit target and rerun the test. |
| The document opens but its image is missing | Compare the file path for the image with the destination folder from the outside note. |
| The file opens and scrolls to the top instead of the decision | Verify that the heading link still matches the destination heading. |
| The app opens the result but a plain viewer fails | Check the reader's link syntax and how it handles a relative path. |
Repeat the filesystem move with a second fresh copy. Let the application finish indexing before inspecting paths. For a synced vault, do tests on a copy outside the sync directory. Sync on two machines can make it harder to tell which device rewrote a reference. If the normal workflow involves both machines, move a disposable folder first and make a backup after the result is known.
Fix a small set of references before moving the rest
Use the test to decide which links must be explicit. For example, a note named Brief can stay short in a project where it is the only one that will be read. Across a vault with years of project archives, a path or a more descriptive filename makes the intended target easier to audit. For a shared decision, add a link from the project summary and open it in the destination reader before you send it.
If readers retrieve notes by half-remembered project names, keep the old title or nickname in the new note where it can be found. Search for the old path after moving a folder, then follow the surviving links. A search for filenames alone may miss a broken heading or attachment. Try the search drills for old project notes once the migration is complete.



