how to jump directly to an org-headline?

Question

If I'm in an org file, I want a command that narrows a candidate list, in ivy/helm style, comprised of all org headlines in the file and lets me choose the headline, through fuzzy searching, to which I want to jump to. Is there a way to do that?

Answer 1

The Org Manual node on Motion gives a somewhat laconic description of the built-in command org-goto (default binding: C-c C-j), whose behaviour can easily be customised to achieve the desired effect:

1. Inspect the documentation of the customisable variable listed at the end of this manual node: C-h v org-goto-interface RET

2. If you are happy to forgo the default org-goto behaviour of incrementally searching through the buffer's outline, you can switch to picking a headline via completion:

   (setq org-goto-interface 'outline-path-completion)
   

3. Users of completion packages like ido/ivy/helm will probably want to change the following setting in order to see the whole target path at once:

   (setq org-outline-path-complete-in-steps nil)
   

   See here for more discussion.

This approach has the added benefit (over using, say, helm-specific functionality) of working with all completion frameworks that plug into the default completing-read, including, as I can personally confirm, ivy.

ADDENDUM:

When using the outline-path-completion interface to the org-goto command as described in this answer, the customisable variable org-goto-max-level determines the maximum depth of headlines to offer.

EDIT:

I found an older, relevant question with useful answers: https://stackoverflow.com/q/15011703/3084001

CLARIFICATION (as prompted by Att Righ's comment):

Setting org-goto-interface to one of the two recognised values does not mean sacrificing the alternative interface. Calling org-goto with a prefix argument (i.e. C-u C-c C-j or C-u M-x org-goto RET) automatically selects the alternative interface for the current completion. This way, you can set org-goto-interface to the interface you are likely to use most often and use the prefix argument when you wish to temporarily switch behaviour. If even this does not suit your needs, you can always write your own wrapper around org-goto, as per Att Righ's example.

Answer 2

I use the package worf, but I bind only one of its functions:

 (use-package worf
    :diminish worf-mode
    :bind (:map org-mode-map ("C-c h" . worf-goto)))

worf-goto gives you a list of the headings in the buffer in the mini buffer, which you can then filter.

The package is made by the author of ivy, so if you like ivy, you might like worf.

Some relevant snippets from worf.el:

;;  - "g" (`worf-goto'): select an outline in the current buffer, with
;;    completion.  It's very good when you want to search/navigate to
;;    a heading by word or level. See https://github.com/abo-abo/lispy
;;    for a package that uses this method to navigate Lisp code.

(defun worf-goto-action (x)
  (with-ivy-window
    (goto-char (cdr x))
    (outline-show-children 1000)
    (worf-more)))

(defun worf-goto ()
  "Jump to a heading with completion."
  (interactive)
  (let ((cands (worf--goto-candidates)))
    (cond ((eq worf-completion-method 'helm)
           (require 'helm-multi-match)
           (let (helm-update-blacklist-regexps
                 helm-candidate-number-limit)
             (helm :sources
                   `((name . "Headings")
                     (candidates . ,cands)
                     (action . worf-goto-action)
                     (pattern-transformer . worf--pattern-transformer)))))
          ((eq worf-completion-method 'ivy)
           (ivy-read "Heading: " cands
                     :action 'worf-goto-action)))))

Answer 3

I find helm-org-rifle particularly nice. Also anything that takes imenu source will be able to display headers (e. g. Helm with imenu).

Answer 4

imenu is built into Emacs and can be paired with helm/ivy to provide the fuzzy search required. I'd recommend helm-org-rifle if you use helm, however.

Answer 5

I use counsel-imenu; it will list the different heads, you can type some letters to narrow your selection and then just press <return>.

Answer 6

Flagrant self-promotion, but you might like to try out orgnav. Which is my kind of alpha (but actively used by me) project for this purpose.

orgnav searches headlines rather than content, can vary the depth of search, search subtrees rather than the entire file (though this can also be achieved with narrowing).

Here's a video of some features: https://asciinema.org/a/1r0fp33xgwh48lfgsh7mllw4u

You should probably also be aware of helm-org package which is part of helm which was the inspiration for this package (or rather whose limitations were the inspiration for this package), as well as helm-org-rifle discussed in other posts.

(Courtesy of answers here: https://www.reddit.com/r/emacs/comments/69mc6l/how_to_jump_directly_to_an_orgheadline/ ) Also potentially of interest is the worf-goto function as part of worf (an org navigation mode that applies a different set of keybindings over "*" before headlines). This seems very much analogous to helm-org.

Answer 7

The swiper library has a new feature in 0.9.0, which is completion for headlines of files in your org-agenda-files.

counsel-org-agenda-headlines

Just need to setup your agenda files list in org init.

(setq org-agenda-files (list "~/org/work.org"
                             "~/org/school.org" 
                             "~/org/home.org"))

In relation to @tirocinium's answer, this provides the same but for many agenda files.

Answer 8

I recommend helm-org-in-buffer-headings. It's built-in to Helm, and it respects narrowed buffers, which is important if you use indirect buffers to edit subtrees independently. There's also helm-org-parent-headings for navigating up a tree, and helm-org-agenda-files-headings for navigating across all agenda files.