bcardoso / org-hop

An interface to hop to Org headings and lines with completing-read, Helm, or Consult

org-hop

An interface to hop to Org headings and lines using completing-read.

helm-org-hop or consult-org-hop provide a richer interface to org-hop.

Installation

Clone this repo and add it to your load-path:

(add-to-list 'load-path "/path/to/org-hop")
(require 'org-hop)
(require 'helm-org-hop)    ; optional Helm interface
(require 'consult-org-hop) ; optional Consult interface

Or, with use-package + straight.el:

(use-package org-hop
  :straight (org-hop :host github :repo "bcardoso/org-hop"
                     :files ("org-hop.el"))
  :bind ("C-c h" . org-hop)
  :config
  ;; optional recent visited headings mode
  (org-hop-recent-mode +1))

;; optional Helm interface
(use-package helm-org-hop
  :straight (helm-org-hop :host github :repo "bcardoso/org-hop"
                          :files ("helm-org-hop.el"))
  :bind ("C-c j" . helm-org-hop))

;; optional Consult interface
(use-package consult-org-hop
  :straight (consult-org-hop :host github :repo "bcardoso/org-hop"
                             :files ("consult-org-hop.el"))
  :bind ("C-c j" . consult-org-hop))

Usage

Just run M-x org-hop or with the suggested binding C-c h.

Or run your preferred command: M-x helm-org-hop or M-x consult-org-hop.

Either way, org-hop will build a list with all findable Org headings (see next section). Additionally, you can store markers to any Org heading or buffer line with the following commands:

• org-hop-add-heading-to-list
• org-hop-add-line-to-list
• org-hop-add-heading-or-line

With the helm-org-hop interface, besides hopping, you can store/insert a link to a heading or a line, and remove them from the recent list.

The org-hop-recent-mode keeps track of the headings you spend some time in (see org-hop-recent-idle-interval).

Recent headings and lines are shown at the top of the general headings list. To remove them, run M-x org-hop-remove-heading-from-list or M-x org-hop-remove-line-from-list.

Customization

The customizable variables are accessible through the customize interface:

• M-x customize-group RET org-hop
• M-x customize-group RET helm-org-hop

By default, org-hop will scan all open Org buffers. You can also edit the variables org-hop-files and org-hop-files-extra to a group of specific files:

(setq org-hop-files 'buffers)        ;; the list of open Org buffers (default)

(setq org-hop-files 'agenda)         ;; the list of Org agenda files

(setq org-hop-files 'org-files-list) ;; Org agenda files + open Org buffers

(setq org-hop-files
      '("x.org" "y.org" "z.org"))    ;; a custom list of Org files


;; Example: the Org agenda files + a custom list, and some files to ignore
(setq org-hop-files        'agenda
      org-hop-files-extra  '("a.org" "b.org")
      org-hop-files-ignore '("some-boring-file.org" "etc.org"))

Use the variable org-hop-files-ignore to specify a list of Org files that should be ignored.

You can also add other sources to helm-org-hop or consult-org-hop commands. See, for example, how to display the current heading’s backlinks with org-backlinks integration.

Related packages

• org-goto (C-c C-j) is a built-in package that allows jumping to a different location in the current file.
• In helm-org, the helm-org-agenda-files-headings and helm-org-in-buffer-headings commands allows searching the headings of all Org files or the current buffer, respectively.
  • The main difference of org-hop’s approach is that headings are shown with their full-path and file-name appended, making it easier to narrow the search.
• alphapapa’s org-recent-headings provides a more sophisticated approach to decide upon recently used Org headings.
  • By contrast, org-hop uses only three simple criteria to consider a heading as “recent” or “visited”: 1) you visited a heading through the (helm-)org-hop interface (much like a history); or 2) you spent some time in a heading (with org-hop-recent-mode enabled); or 3) you added a heading to the recent list with M-x org-hop-add-heading-or-line.
  • helm-org-recent-headings (and/or other helm sources) can be used within the helm-org-hop command:

    (setq helm-org-hop-default-sources '(helm-org-recent-headings-source
                                         helm-org-hop-headings-source))
            

• minad’s consult package provides the commands consult-org-heading and consult-org-agenda for narrowing and jumping to Org headings.

Changelog

v0.3.1

add consult support & bugfixes.

v0.3.0

use org-ql to select Org headings.

v0.2.0

select Org headings with custom cache.

v0.1.0

initial concept & helm interface.

org-hop's Issues

Related packages

My Consult package provides the commands consult-org-heading and consult-org-agenda. These commands seem related to org-hop.