MD: confusing syntax for links to images

The documentation says:

  • ![link](item.png): Use this when linking to an item in the same group as the Markdown document.
  • ![link](group/item.png): Use this when linking to an item in a sub-group of the group containing the Markdown document.
  • ![link](/group/item): Use this when you are linking to an item in a group outside the group containing the Markdown document. For example, if you have common resources in a specific group, you can link to them using this format.

I have two records with the name IMG-1234. The filename of one of them is IMG-1234.HEIC, the other’s is IMG-1234-1.jpg. They are in the same group as my MD document. If in this document I use
to refer to the JPEG image, I get a broken image link in the preview.
If I use
the image preview is ok. But I have no idea which one of the images is shown, as the JPEG is just converted from the HEIC.
Also ![](IMG-1234.HEIC) gives the correct preview. So, using the filename is ok in one case, but not in the other?

I find that irritating. Is the extension (jpg, png, whatever) only required in certain cases (like the documentation states for group-local and relative links, but not for absolute links in another group)? Isn’t that going against the general MD rules, where one has to specify filenames, i.e. including the extension? Why does a correct filename display in one case but not in the other? And if I have to identically named images with differing filenames, which one will be displayed by DT?

Links inside the database use names, not the rarely visible filenames (which might or might not be identical to the shown name). Groups do not even have a filename/path.

And which image is shown if records with identical names exist at the same place? How would I choose one over the other in my MD file in that case?

What does that mean? I know that there doesn’t exist a corresponding object in the file system for a group, and I was talking about the name/filename for the image in a group.

But why is the documentation using complete filename (group/item.png) as well as record name (/group/item)? Shouldn’t the syntax be the same, i.e. with extension or without in both cases?

By using the item link or a unique name only.

It isn’t. It’s just the name with the extension, similar to the preferences to show the extensions.

.heic isn’t supported for Markdown images. Do you have a screen capture of this?


In this instance, with two images with the same name but different by format (therefore extension), which one is DEVONthink supposed to link to? Including the extension makes it very clear.

And moving the heic file out of the img group, both jpeg links work with and without the extension…

Here, it seems to work. Same group, preferences set to not display extensions with name.

Why wouldn’t it be inside DT? The preview relies on Webkit, aka Safari. And that is the only browser supporting HEIC images:

WebKit in Safari is not the same as used in DEVONthink.