git clone 'git://'

navi-mode.el — major-mode for easy buffer-navigation

Author: Thorsten Jolitz Version: 2.0 URL:


copyright: Thorsten Jolitz

copyright-years: 2013+

version: 2.0

licence: GPL 2 or later (free software)


part-of-emacs: no

author: Thorsten Jolitz

author_email: tjolitz AT gmail DOT com


git-clone: git://

inspiration: occur-mode org-mode

keywords: emacs navigation remote-buffer-control


About navi-mode

Navi-mode, as its name suggests, enables super-fast navigation and easy structure-editing in Outshine or Org buffers via one-key bindings in associated read-only Navi buffers.

You can think of a navi-buffer as a kind of ‘remote-control’ for an (adecuately) outline-structured original-buffer. Besides navigation and structure-editing, many common commands can be executed in the original-buffer without (necessarily) leaving the navi-buffer. When switching to the original-buffer and coming back after some modifications, the navi-buffer is always reverted (thus up-to-date).

Besides the many things that can be done from a navi-buffer, its main benefit is to offer a flexible but persistent and rock-solid overview side-by-side to the details of the original buffer. There can be many different navi-buffers alive at the same time, each one of them firmly connected to its associated original buffer. Switching between the ‘twin-buffers’ is easy and fast. Typically, an outline-structured original buffer in ‘show-all’ visibility state shares a splitted window with its associated navi-buffer that either shows headlines, keywords, or a combination of both. Instead of cycling visibility in the original buffer itself it is often more convenient to quickly switch to its navi-buffer and use its many different (over-)views.

Navi-mode is implemented on top of occur-mode and thus uses occur as its ‘search-engine’. It does not aim to replace occur-mode or to compete with it, it rather specializes occur-mode for a certain use-case. Using navi-mode for remotely controlling Outshine and Org buffers does in no way interfere with occasionally calling ‘M-x occur’ on these buffers.

Navi-mode is part of the Outshine project, consisting of the three libraries outshine.el, outorg.el and navi-mode.el. For navi-mode to work, the original buffer must be either an org-mode buffer or have outline-minor-mode with outshine extensions activated (and be structured with outshine headers, i.e. outcommented Org headers).


Navi-mode is a special read-only mode (line e.g. occur-mode and dired-mode), thus all its core commands have one-key bindings. However, the command `navi-edit-mode' makes the navi-buffer editable. The edits are directly applied in the associated original buffer. With command `navi-cease-edit' the default read-only mode is turned on again.

Navi-mode's functionality can be divided into the following categories:

Besides the mentioned fundamental outline-heading-searches (8 outline-levels) and the 5 basic keyword-searches (:FUN, :VAR, :DB, :OBJ and :ALL), all languages can have their own set of searches and keybindings (see customizable variables `navi-key-mappings' and `navi-keywords').

Use ‘M-s n’ (`navi-search-and-switch') to open a navi-buffer and immediately switch to it. The new navi-buffer will show the first-level headings of the original-buffer, with point at the first entry. Here is an overview over the available commands in the navi-buffer:

key command function-name
1 … 8 show levels 1 to 8 navi-generic-command
key command function-name
p previous occur-prev
n next occur-next
DEL down page scroll-down-command
SPC up page scroll-up-command
key command function-name
g revert buffer navi-revert-function
h show help navi-show-help
q quit navi-mode and switch navi-quit-and-switch
key command function-name
M-s n launch navi-buffer navi-search-and-switch
M-s s switch to other buffer navi-switch-to-twin-buffer
M-s M-s    
d display occurrence occur-mode-display-occurrence
o goto occurrence navi-goto-occurrence-other-window
key command function-name
TAB cycle subtrees navi-cycle-subtree
cycle buffer navi-cycle-buffer
+ Demote Subtree navi-demote-subtree
- promote subtree navi-promote-subtree
^ move up subtree (same level) navi-move-up-subtree
< move down subtree (same level) navi-move-down-subtree
key command function-name
m mark thing at point navi-mark-thing-at-point-and-switch
c copy thing at point navi-copy-thing-at-point-to-register-s
k kill thing at point navi-kill-thing-at-point
y yank killed/copied thing navi-yank-thing-at-point-from-register-s
u undo last change navi-undo
r narrow to thing at point navi-narrow-to-thing-at-point
w widen navi-widen
l query-replace navi-query-replace
i isearch navi-isearch
e edit as org (outorg) navi-edit-as-org
. call fun on thing at point navi-act-on-thing-at-point
key keyword-symbol searches for
f :FUN functions, macros etc.
v :VAR vars, consts, customs etc.
x :OBJ OOP (classes, methods etc)
b :DB DB (store and select)
a :ALL all

(example Emacs Lisp):

                        a : ALL
                        f : FUN
                        v : VAR
                        x : OBJ
                        b : DB
                        F : defun
                        V : defvar
                        C : defconst
                        G : defgroup
                        U : defcustom
                        A : defadvice
                        W : defalias
                        M : defmarcro
                        D : defface
                        S : defstruct
                        B : defsubst
                        L : defclass
                        I : define
                        J : declare
                        K : global-set-key
                        T : add-to-list
                        Q : setq
                        H : add-hook
                        O : hook
                        X : lambda
                        Z : ert
                        R : require

in an Emacs Lisp (outshine-)buffer shows all headlines up-to level 2 as well as all function, macro and advice definitions in the original-buffer,

C-5 a

shows all headlines up-to level 5 as well as all functions, variables, classes, methods, objects, and database-related definitions. The exact meaning of the standard keyword-searches ‘f’ and ‘a’ must be defined with a regexp in the customizable variable `navi-keywords' (just like the user-defined keyword-searches).

When exploring a (potentially big) original buffer via navi-mode, a common usage pattern is the following:

  1. type e.g ‘2’ and go to the relevant headline
  2. type ‘r’ and e.g. ‘3’ in sequence to narrow buffers to the subtree at point and show one deeper level of headlines
  3. do your thing in the narrowed subtree
  4. type e.g. ‘2’ and ‘w’ to first reduce the headline levels shown and then widen the buffers again.


Install the three required libraries:

navi-mode.el [navi-mode](
outshine.el [outshine](
outorg.el [outorg](

from the package-manager via MELPA or clone their github-repos. Follow the installation instructions in `outshine.el' and `outorg.el'.

Then install `navi-mode.el' by adding

(require 'navi-mode)

to your .emacs file.

Emacs Version

`navi-mode.el' works with [GNU Emacs 24.2.1 (x86_64-unknown-linux-gnu, GTK+ Version 3.6.4) of 2013-01-20 on eric]. No attempts of testing with older versions or other types of Emacs have been made (yet).


date author(s) version
<2014-09-20 Sa> Thorsten Jolitz 2.0
<2013-05-03 Fr> Thorsten Jolitz 1.0
<2013-03-11 Mo> Thorsten Jolitz 0.9