10

I want to use Org-Mode as a wiki so I need to have an index of all my org files. In it I want to have a list of links to all those files, but my problem is that I have found no way to link pages with IDs and not their names.

Obviously I want the names of the files to not appear anywhere on the link. The reason for this is that I change the name of files regularly so if I use them, the links are going to break constantly. How can I achieve it?

Adam
  • 2,407
  • 2
  • 21
  • 38

1 Answers1

16

Customize the variable org-id-link-to-org-use-id and set it to t (AKA Create ID to make link). Then when you do C-cl (i.e. org-store-link), an ID property will be added to the headline with a UUID as value. When you save the link somewhere else (perhaps in another file) with C-cC-l (i.e. org-insert-link), the link will appear like this:

[[id:b7b07a14-5dbb-48ed-9d9d-70df49e83231][Heading]]

Clicking it will take you back to the file and heading that has this UUID as the value of its ID property.

You might find that creating an ID every time you store a link (particularly if that happens as a result of a capture) creates a lot of useless IDs. The other possible values of org-id-link-to-org-use-id might help. The docstring says:

Non-nil means storing a link to an Org file will use entry IDs.

The variable can have the following values:

t     Create an ID if needed to make a link to the current entry.

create-if-interactive
      If ‘org-store-link’ is called directly (interactively, as a user
      command), do create an ID to support the link.  But when doing the
      job for capture, only use the ID if it already exists.  The
      purpose of this setting is to avoid proliferation of unwanted
      IDs, just because you happen to be in an Org file when you
      call ‘org-capture’ that automatically and preemptively creates a
      link.  If you do want to get an ID link in a capture template to
      an entry not having an ID, create it first by explicitly creating
      a link to it, using ‘C-c l’ first.

create-if-interactive-and-no-custom-id
      Like create-if-interactive, but do not create an ID if there is
      a CUSTOM_ID property defined in the entry.

use-existing
      Use existing ID, do not create one.

nil   Never use an ID to make a link, instead link using a text search for
      the headline text.

You can customize this variable.

Some experimentation will be needed to find what's comfortable for you.

NickD
  • 27,023
  • 3
  • 23
  • 42
  • Thank you, nice answer. – Adam Jul 23 '19 at 16:07
  • 2
    How does org find this ID later? – HappyFace May 09 '21 at 07:21
  • 4
    It uses a (hidden) file `.org-id-locations` in your `user-emacs-directory` (in my case, that is `~/.emacs.d`). – NickD May 09 '21 at 13:53
  • 3
    @NickD How to make this ID locations cache update after files are renamed (i.e., when the linked file is not where the cache says it should be)? – HappyFace May 10 '21 at 13:48
  • No easy way, AFAIK: cache invalidation is a hard problem. Avoidance is probably the easiest way to not have the problem in the first place: do not move/rename files that contain custom IDs. Otherwise, you need to find out where the file got moved/renamed and go back and fix up the cache file. If there is an easier way, I don't know it. – NickD May 10 '21 at 14:30
  • 1
    That defeats the whole point of using IDs instead of filenames to do the linking. :( – hennes Aug 06 '21 at 10:29
  • 2
    @NickD, do you know if org-mode is able to reconstruct that .org-id-locations file if the latter gets damaged, deleted, or otherwise rendered unusable? – tkp Sep 03 '21 at 22:54
  • 3
    How about `org-id-update-id-locations` to re-scan the files? – Rudolf Adamkovic May 24 '22 at 06:05
  • Thanks Rudolf. That's exactly what I was looking for. – tkp Jul 01 '22 at 17:08
  • 1
    You may need to run `(org-id-update-id-locations (directory-files-recursively org-roam-directory ".org$\\|.org.gpg$"))` to scan all the locations. You may further need to add all the locations needed if this command does not cover all your locations. (see [this](https://github.com/org-roam/org-roam/issues/1702#issuecomment-888998330)) – Inspired_Blue Sep 29 '22 at 10:57