+
Skip to content

bcardoso/org-backlinks

Repository files navigation

org-backlinks

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.

screenshot.png

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.

diagram.png

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.

Installation

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 interface

Or, 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))

Usage

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.

Integration

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)

Arbitrary link types

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"))

Changelog

v0.3.0
Add support for arbitrary link types.
v0.2.0
Add Consult support.
v0.1.0
Initial concept & Helm interface.

About

An interface for searching backlinks to Org headings.

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published
点击 这是indexloc提供的php浏览器服务,不要输入任何密码和下载