As I mentioned yesterday, I started organizing (and cleaning) my Emacs config. What may have seemed like an annoying and boring task has proven to be fun and addicting (reminds me of this, which is part of this video 😂).

I’ve already discovered a couple of new improvements to my current config as I was researching individual settings and why I have them, and as I said I do plan to share it. For now though, one important section I added to my config is a quick org-mode links reference. This is actually the first time I figured out the difference between radio links and “regular” plain links and how to use them.

Here it is, slightly modified:

Org-ID

We know about links to other files using org-id: You give a header an :ID: property (this is generated automatically1 when you link to a header) and you get a slug, usually a UUID (for me it’s something slightly else, more on that soon below). This stores the links in org-id-locations, which in turn points to a local file with all of these unique IDs. This is good for linking between headers in different files.

Custom-ID

We can set a :CUSTOM_ID: property for a header, and it’s only active in that file. Kind of like a table of contents in a book, with chapters (= headers) listed. If you don’t have the book, you don’t have its table of contents, so you know nothing about it.

These are buffer-specific only (no cross-reference between files). In this case, the links are tied to words (anchors), not headers. There are two kinds.

The regular plain target link works when we set the anchor first with <<an anchor>>, then call it again with [[an anchor]].

Its more “magical” brother is a radio target link, where we set an anchor like so <<<very special anchor>>> (three angle brackets) and then all we need to do is type very special anchor (no brackets this time), and it works. Note though that when you create a radio target for the first time, you have to revert the buffer or M-x org-update-radio-target-regexp for it to take effect.

Footnotes

1 : this can be done with a function, org-id-get-create. For a deeper dive into how and why I set my org-id with a date format (not UUID), look here.