An interface for searching backlinks to Org headings.
This package aims to provide a sense of context when searching for links to and from the current note.
Backlinks are the Org headings that have links to the current Org heading at point. Second order backlinks are the backlinks to each of the current heading’s backlinks. Third order backlinks are the same but for the second order ones.
Optionally, it can also show the direct and indirect links of a note.
Direct links are the links to other headings present in the current heading. Indirect links are the direct links present in those headings.
The optional packages helm-org-backlinks and consult-org-backlinks provide a Helm and a Consult interface for org-backlinks.
This package requires org-ql.
Clone this repo and add it to your load-path:
(add-to-list 'load-path "/path/to/org-backlinks")
(require 'org-backlinks)
(require 'helm-org-backlinks) ; optional Helm interface
(require 'consult-org-backlinks) ; optional Consult interfaceOr, with use-package + straight.el:
(use-package org-backlinks
:straight (org-backlinks :host github :repo "bcardoso/org-backlinks"
:files ("org-backlinks.el"))
:bind ("C-c z" . org-backlinks))
;; optional Helm interface
(use-package helm-org-backlinks
:straight (helm-org-backlinks :host github :repo "bcardoso/org-backlinks"
:files ("helm-org-backlinks.el"))
:bind ("C-c z" . helm-org-backlinks))
;; optional Consult interface
(use-package consult-org-backlinks
:straight (consult-org-backlinks :host github :repo "bcardoso/org-backlinks"
:files ("consult-org-backlinks.el"))
:bind ("C-c z" . consult-org-backlinks))Just run M-x org-backlinks (or with the suggested binding, C-c z) in a Org heading. It will display all known backlinks to the current heading.
Alternatively, run your preferred command interface: M-x helm-org-backlinks or M-x consult-org-backlinks.
org-backlinks will search the files defined by org-backlinks-files for links to the ID or CUSTOM_ID properties of the current Org heading.
Set org-backlinks-show-direct-links to t to see both the direct and indirect links to other headings that are present in the current heading.
Other customizable variables are accessible through the customize interface:
M-x customize-group RET org-backlinks.
org-backlinks sources can be easily integrated into other Helm or Consult commands.
For example, this is how I integrate a simple backlink source into org-hop, my all-purpose Org heading hopping interface:
;; Consult interface
(require 'consult-org-backlinks)
(advice-add 'consult-org-hop :before #'org-backlinks-setup-simple)
(add-to-list 'consult-org-hop-sources 'consult-org-backlinks-source)
;; Helm inferface
(require 'helm-org-backlinks)
(advice-add 'helm-org-hop :before #'org-backlinks-setup-simple)
(add-to-list 'helm-org-hop-default-sources 'helm-org-backlinks-source)By default, both ID and CUSTOM_ID properties are considered when searching for backlinks.
Now suppose you have defined a custom link parameter (say, my) that depends on the values of an specific Org property (say, MY_ID).
(org-link-set-parameters "my" :follow #'my-follow-function)This way, for example, following a link like my:123 would lead you to an Org heading where the value of property MY_ID is “123”.
(The actual implementation of such “follow function” is irrelevant here, as it will not be called by org-backlinks. The important part is that the new link type must be set properly, so direct links can be found with org-element-map.)
With enough links of this type among your notes, it might be useful to see the structure of backlinks and other indirect links for the current heading as if they were standard Org links.
To include an arbitrary link type along with the default ID and CUSTOM_ID properties, just add it to org-backlinks-link-types:
(add-to-list 'org-backlinks-link-types (cons "my" "MY_ID"))