3.5 KiB
org-unique-id
Introduction
org-unique-id is a utility package for org users that are tired
dealing with random org IDs for their headers that change on each org
to HTML export (and other kinds of exports). This package creates
meaningful custom IDs for org headers that won’t change unless the
user modifies them manually.
Table of Contents TOC_2_gh
Installation
This package can be installed like any other simple package. Your
first option is to download org-unique-id or clone this package in
your load-path and add the following to your configuration:
(require 'org-unique-id)
(add-hook 'before-save-hook #'org-unique-id-maybe)
You can also use a package manager such as Quelpa or Straight in order
to load automatically your package. In my case, I prefer the latter
with its use-package integration:
(use-package org-unique-id
:require t
:after org
:straight (org-unique-id :type git
:host github
:repo "Phundrak/org-unique-id")
:init (add-hook 'before-save-hook #'org-unique-id-maybe))
I personally add :build t to my straight recipe to ensure my package is compiled.
If you know how to handle this with a pure Straight recipe, or with a Quelpa recipe, don’t hesitate to submit a PR to add it to this README!
Usage
While org-unique-id may be installed on your Emacs instance, it is not
active by default. This is because it can take some time to generate
all the required IDs in your org file which may hang your Emacs
instance for a bit. Therefore, automatic IDs are enabled on a per-file
basis with the option unique-id.
Here is an example of an org buffer with org-unique-id enabled:
#+title: Test file
#+options: unique-id:t
* Test level 1
:PROPERTIES:
:CUSTOM_ID: Test-level-1-zmb40t305kj0
:END:
** Test level 2
:PROPERTIES:
:CUSTOM_ID: Test-level-1-Test-level-2-spn40t305kj0
:END:
* Test level 1
:PROPERTIES:
:CUSTOM_ID: Test-level-1-1nx40t305kj0
:END:
The CUSTOM_ID properties are generated on save and only once. Once the
CUSTOM_ID of a heading is set, the package will not modify it even if
the name of the heading itself is modified. To regenerate it, delete
the CUSTOM_ID and let org-unique-id regenerate it. If you don’t like
the CUSTOM_ID generated by org-unique-id, you can overwrite it
yourself and org-unique-id will not modify it.
Note that unique-id:t is absolutely required in order to get these
CUSTOM_ID. Here is the same buffer after save without this option:
#+title: Test file
* Test level 1
** Test level 2
* Test level 1
It is also possible to manually call org-unique-id (interactively or
not) on the current buffer. This will not check the value of the
unique-id option.
Breaking changes
0.4.0
The option auto-id is renamed to unique-id.
Contributing
License
org-unique-id is available under the GNU GPL-3.0 license. You can find
the full text in LICENSE.md.