107 lines
3.7 KiB
Org Mode
107 lines
3.7 KiB
Org Mode
#+title: org-unique-id
|
||
#+author: Lucien Cartier-Tilet
|
||
#+email: lucien@phundrak.com
|
||
[[https://github.com/Phundrak/org-unique-id/actions/workflows/workflow.yml][file:https://github.com/Phundrak/org-unique-id/actions/workflows/workflow.yml/badge.svg]]
|
||
[[https://melpa.org/#/org-unique-id][file:https://melpa.org/packages/org-unique-id-badge.svg]]
|
||
[[https://stable.melpa.org/#/org-unique-id][file:https://stable.melpa.org/packages/org-unique-id-badge.svg]]
|
||
|
||
* 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:
|
||
- [[#introduction][Introduction]]
|
||
- [[#installation][Installation]]
|
||
- [[#usage][Usage]]
|
||
- [[#breaking-changes][Breaking changes]]
|
||
- [[#040][~0.4.0~]]
|
||
- [[#contributing][Contributing]]
|
||
- [[#license][License]]
|
||
|
||
* 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:
|
||
#+begin_src emacs-lisp
|
||
(require 'org-unique-id)
|
||
(add-hook 'before-save-hook #'org-unique-id-maybe)
|
||
#+end_src
|
||
|
||
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:
|
||
#+begin_src emacs-lisp
|
||
(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))
|
||
#+end_src
|
||
|
||
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:
|
||
#+begin_src org
|
||
,#+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:
|
||
#+end_src
|
||
|
||
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:
|
||
#+begin_src org
|
||
,#+title: Test file
|
||
,* Test level 1
|
||
,** Test level 2
|
||
,* Test level 1
|
||
#+end_src
|
||
|
||
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
|
||
See [[file:CONTRIBUTING.org]].
|
||
|
||
* License
|
||
~org-unique-id~ is available under the GNU GPL-3.0 license. You can find
|
||
the full text in [[file:LICENSE.md][LICENSE.md]].
|