Skip to content

Decide on the internal links format

Goal

Only use one link format across the vault. (core, plugins, frontmatter)

Reason

Data consistency. Pre-requisite for painless (future) migration tasks, publishing, cross-editor note-taking.

Conclusion

Own preference: shortest path + markdown links

Details

Keep the standard. There is a chance that the notes work outside of Obsidian without adjustment (like in git platforms)

Reason for shortest path

[!ABSTRACT] TL;DR Use [markdownlinks](shortestpath.md) as long as you use Obsidian. If you decide to replace Obsidian, one-time convert links to [markdownlinks](../relative/paths.md).

This is a tough one. shortest path is a proprietary Obsidian feature (also called smart linking) allowing linking notes without any folder or path information as long as the note name is unique.

[!IMPORTANT] The incredible high value of shortest path is that links to a note don't have to change if that note is moved to another folder of if the vault structure changes (folder moved or renamed, nesting level changed).

Imagine renaming the folder myprojects to projects. Any links from notes outside of that folder to notes inside would have to be changed if links are either relative or absolute. This is done automatically by Obsidian, but having the content of hundreds of thousands of notes changed just because a folder name was changed, produces a lot of noise. Especially when using git versioning for the notes this adds a lot of unnecessary clutter.

[!NOTE] When only absolute or relative are available options, I highly prefer relative because such a link always works regardless of where the vault is published or if only part of a vault is published.

What that means: - When using absolute paths, every single link will break if the root location where the vault is published is not the vault root itself (And there is an extremely high probability, that for technical reasons you cannot or should not publish the vault as root of your target platform). - With absolute paths, every single link will also break if you publish just a specific subfolder, because all links will start with a non-existent parent. - In both cases, relative links work. Which means, they always work after publishing.

However, relative links need to be updated when they link to notes in different folders and the intermittent folder name changes. The links also change if the note itself is moved to a folder with different nesting level, because ..\..\noteB.md might now be reached as ..\noteB.md when noteA.md is moved one folder up.

That means, the more folders you use in your vault the more you will be constantly adjusting relative paths. Again, Obsidian does that automatically (however, see warning) but it adds a lot of noise to the version history.

WARNING on relative paths

Having used relative links for some time I have found that it has a huge drawback in Obsidian: When copy & pasting links between notes or moving notes or creating links from plugins, they always have to be "recalculated" to get the relative path from the source to the target note right. This is not the case.

Some plugins calculate the path from the wrong note (imagine having focus on noteA and triggering a plugin that creates noteB and adds a link to noteC to it). Don't blame them, if you manually cut & paste text with a link into a different note you might end up with an invalid relative path as well.

[!QUESTION] But, but, but... everything works for me, so maybe my Obsidian and plugins all get it right?

Unfortunately, no.1 The reason that everything works is because of Obsidian' smart linking algorithm (see above). Even if the nesting levels in relative links are totally messed up, Obsidian does not care because it finds the note anywhere as long as it can be identified by its unique2 name.

[!HINT] The takeaway Because Obsidian resolves links in a smart way, relative paths in your vault will break without you noticing it.

However, the whole reason to accept the overhead and use standard relative links instead of proprietary shortest links in Obsidian was that those relative links would work in any external markdown tool out of the box. This is not guaranteed because Obsidian does not care about inaccurate relative links!

[!INFO] Some might argue that "well, if relative links are bugged, they should fix it.". I guess this depends on the perspective. For Obsidian developers, the main goal seems to be usability / user experience. Conforming with standards can be a conflicting goal. In this case, if they are able to resolve a link, they will always do that, even if the link (path) is invalid by common standards.

If you consider this a bug, a "fix" would require them to disable their smart linking on relative links and add a tool for the user to repair broken links. This would increase conformity at the cost of user experience. I'm pretty confident that this will never happen, although I personally would agree that this is the right thing to do (i.e. enable smart linking for users choosing "shortest path" and disable smart linking and enforce full compliance for users choosing "relative path").

A middle way might be a feature request for Obsidian to add a visual indicator on relative links that only resolve because of smart linking and an option to fix them.

CONCLUSION

Relative paths are complicated to maintain. They must be valid because otherwise you will lose relationships between notes. Using relative links with Obsidian is dangerous because you will (rightfully) expect that even without Obsidian, those will work as standard markdown links. This does not hold true, because Obsidian does not enforce relative paths to be true/valid relative paths.

Therefore you should either use [[wikilinks]] or [markdownlinks](shortestpath.md). Only those two align with Obsidians smart linking and thus have a guaranteed state of either valid + working or invalid + broken (note: all other options can be invalid + working).

If you want to use the links outside, you need to convert them. This is straight forward thus not a lock-in. All links in the vault could also one-time converted to absolute or relative paths with ease should you decide to stop using Obsidian.

There is a small benefit of the [markdownlinks](shortestpath.md) version over [[wikilinks]]: For relationships within the same folder (i.e. sibling notes) this shortest path is even a valid relative path and it will work outside of Obsidian. That means, if your vault only contains few folders to separate notes with entirely different context from each other, a lot of links will still be perfectly valid standard relative markdown links "by coincidence".

  • val3344/obsidian-update-relative-links #status/needs-review
    • This is a plugin trying to fix relative links that Obsidian does not care about.
    • Maybe it can be also used to fix old relative paths from before switching back to shortest?
  • Tool to convert everything to [markdownlinks](shortestpath.md):
    1. Change Obsidian config to shortest path
    2. Use Obsidian.Packages.Consistent Attachments and Links to convert all links.
  • Tool to convert everything to [markdownlinks](../relative/paths.md):
    1. Change Obsidian config to relative path
    2. Use Obsidian.Packages.Consistent Attachments and Links to convert all links.

References

  1. Unless you don't use any folders in your vault. In which case shortest is relative and we need not discuss further at all. ↩

  2. or even by just getting the closest neighbour otherwise. ↩