Image embedding: why incompatible syntax was chosen?

Obsidian uses this syntax to embed images: ![[]]. As far as I can see this is some kind of wikiimage extension syntax.
Licat, Silver: can you, please, bring a light: why this exact syntax was chosen? There is no other markdown editor which supports this kind of image embedding, which raises some compatibility issues. Are there some benefits of using ![[...]]?



A quick note: please don’t tag our lovely developers unless something is particularly critical or urgent. They see every post when they get the chance, and us volunteer mods flag things for them!

(This is my opinion, not their decree. But if everyone tagged the devs with every question, the mentions feature would be useless.)


I removed the @-tagging by your request, but this was a direct question to the devs (not the everyone tagged the devs with every question one), so I was sure the tagging was quite appropriate.


@Valery_Kondakoff, hi again, see this post.

Hi, Alexander!

In the thread you suggested I don’t see any answer on an original question: Why the devs decided to use incompatible syntax for image embedding? Are there any benefits of using [[...]] instead of ![](...)?

Am I’m missing something?

1 Like

Hmm… I was wrong. Here is some info:

Any other glues?

1 Like

There’s a comment by WhiteNoise saying:

We have decided to go with a more compact notation for links and images to improve interpretability and and ease of use. It’s the same syntax used by wikipedia and other software.

1 Like

Perfect synchronisation! :wink:

1 Like

To me the motivation behind this decision is quite transparent: the guy who is behind original Markdown syntax has blamed himself for choosing the unreadable format to insert images (cannot find the link to prove this right now). So having Obsidian support both standard markdown for images as well as simplified notation is a good thing, IMO.

Also, you don’t seem to be worried about “incompatible” links format in Obsidian which had similar rationale, I guess.

These don’t appear critical to me. Should something happen to Obsidian, we can use any text editor and simple RegEx to replace all those “incompatible” pieces of syntax with “more compatible” ones.

This is not a good example, because there is no ‘standard/compatible’ internal links syntax yet: [](url://filename.extension) is just an external linking using URL schemes. And wiki links are the closest to standard (as far as I can see).

I’m not worrying about incompatible image embedding syntax. I was just unable to find any other app (on Mac and iOS) to support this syntax and was curious enough to try to find the reasons of supporting exactly this syntax in Obsidian.

Speaking on this. Here is the quote:

There may be a good idea to introduce an option ‘Use standard image embedding syntax’ in Obsidian preferences for these, who are using their notes with other software.


If by internal links you mean links to another file in a vault, these are by nature external links, not internal, so Markdown and URI schemes syntax has them covered. Same goes for intra-file links or anchors. Is it convenient to type and to maintain though? Certainly not. Hence wiki-style links both for links and for images.

Luckily, the developers seem to agree with you as seen in the post above.

1 Like

Just found ‘Export to standard markdown links’ in an Obsidian roadmap:

Снимок экрана 2020-08-04 в 18.41.51

Maybe this includes images embedding as well? Unfortunately this is just an export, and not an option to use standard markdown links instead of proprietary. But still sounds promising…

1 Like

Just FYI, not every improvement is on the roadmap! I imagine “export to standard markdown links” is separate from a feature adding a preference toggle for in-vault image syntax (or whatever).

(I.e., just because something isn’t explicitly called out on the roadmap doesn’t mean it isn’t in development.)

The ![[]] embed syntax is more consistent with embedding other contents, like videos or entire notes, which is not supported by vanilla Markdown. Similar to the relationship of [Link](link) and [[link]].

We will add an option to auto-complete Markdown links and images instead of our format in the future, for those who want max interoperability with the cost at seeing some redundant text. Hope that helps.


Great! Thanks!