Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/phundrak/org-unique-id

Create meaningful and persistant org IDs automatically
https://github.com/phundrak/org-unique-id

emacs emacs-orgmode org-mode

Last synced: 5 days ago
JSON representation

Create meaningful and persistant org IDs automatically

Awesome Lists containing this project

README 

        
#+title: org-unique-id

#+author: Lucien Cartier-Tilet

#+email: [email protected]

[[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]].