Suppose you have an org-mode file and want an image to appear in the buffer. The way to do that is to insert a link to the file, for example:

[[home/username/downloads/image.png]].

Then, you toggle inline images with C-c C-x C-v, and the image should display inside the org-mode buffer, provided the path in the link is correct. If you do this often in your notes as I do, you might as well just turn it on for the entire file with #+STARTUP: inlineimages at the top of your org file, with the rest of the options you have there; this way, images will always display when you load the file. This is all nice and good, and most of us org-mode users probably know that.

A common use case for a full workflow like this is attaching images to your org file. You have a file in your Downloads folder, as shown in the example above, and you want to keep the image with your org file where it belongs, rather than in Downloads, where it will be lost among other files sooner or later.

For this, as most of us know, we have org-attach (C-c C-a by default). This starts a wonderful organizational process for our files:

  1. It creates a data folder (by default) inside the folder the org-file is in if it’s not there
  2. It then gives the header (even if you don’t have one) a UUID (Universally Unique Identifier) and creates two more directories, one inside the other:
    1. The parent directory consists of the first part of the UUID
    2. The child directory consists of the rest of the UUID
  3. Lastly, the file itself will be copied into the child directory above.

For example:

./data/acde070d/8c4c-4f0d-9d8a-162843c10333/someimage.png

If you’re not used to how org-attach works, it might take some time getting used to, but it’s worth it. Images (or any file, as we will deal with soon) are kept next to the files they are associated with. Of course, org-attach is customizable, and you can change those folders and UUIDs to make them less cryptic.

For example, my init includes this:

    (setq org-id-method 'ts)
    (setq org-attach-id-to-path-function-list 
      '(org-attach-id-ts-folder-format
        org-attach-id-uuid-folder-format))

This tells org-mode to change the UUID to IOS date stamp format, so the folders under the data folder are dates, and tells org-mode to use that system (I wrote about this in length in my old blog; it is yet another post I need to bring over here).

In my case, this creates a file reference system by date: inside the data folder, each month of the year has a folder; inside those, a folder for the day and time (down to fractions of seconds) of the attachment. The beauty of org-attach is that you’re not meant to deal with the files directly. You summon the org-attach dispatcher and tell it to go to the relevant folder (C-c C-a to bring it up, then f as the option to go to that directory).

org-attach and displaying images inline are known to many org-mode users, but here comes the part I never realized:

org-attach stores the link to the file you just attached inside a variable called org-stored-link, along with other links you might have grabbed like URLs from the web (take a look with C-h C-v org-stored-links). And, even better, these links are added to your org-insert-link, ready to go when you insert a link to your file with C-c C-l.

So when you have an image ready to attach to an org file, say in your Downloads folder, you could first attach it with org-attach, and then you can call it back quickly with C-c C-l. The trick is, since this is an image link (and not just any file), is not to give it a description. By default, org-mode will suggest you describe the link as the file you attached, but inline images do not work like that, and with a description, the image will just display as a file name. In other words:

A link to an image you want to display in the org buffer should look like:

[[file:/Home/username/downloads/someimage.jpg]]

But any other file would look like:

[[file:/Home/username/downloads/somefile.jpg][description]]

By deleting the suggestion, you are effectively creating the first case, the one that is meant to display images. This is explained nicely here.

There’s more to it. As it turns out, the variable org-attach-store-link-p is responsible for the links to these files to automatically be stored in org-insert-link (you can toggle it to change this option). This is why, when you use it, your files or images will show as [[attachment:description]], without the need for the path as specified above.

I have years of muscle memory to undo, as I’m used to manually inserting the links with the full path for my images. I did not realize the links to the images I’ve attached are right there, ready for me to place into the buffer if I only delete the description.