You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
Lucien Cartier-Tilet 1a4c2c6bb9
Add issue templates for Github
3 months ago
.github Add issue templates for Github 3 months ago
.dir-locals.el Update CONTRIBUTING and dir variables 3 months ago
.gitignore Add gitignore 4 months ago
CONTRIBUTING.org Fix links in CONTRIBUTING 3 months ago
Eask Update Eask information 3 months ago
LICENSE.md Change some function names, add README, LICENSE and CONTRIBUTING 1 year ago
Makefile Add CI 4 months ago
README.org Add MELPA badges 3 months ago
org-unique-id.el Bump to version 0.4.1 3 months ago

README.org

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

org-unique-id

file:<img src=" title="file:https://github.com/Phundrak/org-unique-id/actions/workflows/workflow.yml/badge.svg" /> file:<img src=" title="file:https://melpa.org/packages/org-unique-id-badge.svg" /> file:<img src=" title="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 wont change unless the user modifies them manually.

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, dont 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 dont 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.

License

org-unique-id is available under the GNU GPL-3.0 license. You can find the full text in LICENSE.md.