Skip to content
A helpful sidebar for Org mode
Emacs Lisp Shell Makefile
Branch: master
Clone or download
Latest commit b5eff71 Oct 17, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
LICENSE More improvements May 23, 2018
Makefile Meta: Add, Makefile Sep 8, 2019 Add: tree-cycle-global Oct 12, 2019 Docs: Update examples Sep 8, 2019 Meta: Add, Makefile Sep 8, 2019 Notes: Add idea Oct 17, 2019
org-sidebar.el Comment: Add TODO Oct 12, 2019


This package presents helpful sidebars for Org buffers. Sidebars are customizable using org-ql queries and org-super-agenda grouping.

The default sidebar includes a chronological list of scheduled and deadlined items in the current buffer (similar to the Org agenda ,but without all its features) at the top, and a list of all other non-done to-do items below. If the buffer is narrowed, the sidebar only shows items in the narrowed portion; this allows seeing an overview of tasks in a subtree.


The tree-view sidebar aids navigating an outline and editing entries individually:





If you installed from MELPA, you’re done!


Installing with Quelpa is easy:

  1. Install quelpa-use-package (which can be installed directly from MELPA).
  2. Add this form to your init file:
(use-package org-sidebar
  :quelpa (org-sidebar :fetcher github :repo "alphapapa/org-sidebar"))

You may find this function helpful for updating packages with Quelpa.


Call these commands to display sidebars:

  • org-sidebar-tree: Display tree-view sidebar for current Org buffer.
    • org-sidebar-tree-toggle: Toggle tree-view sidebar.
  • org-sidebar: Display the default item sidebars for the current Org buffer.
    • org-sidebar-toggle: Toggle default sidebars.


Customization options are in the org-sidebar group. For example, you can add the tree view to the default sidebar:


Showing theme doom-one-light.

Or you can display the tree sidebar on one side, and the item sidebars on the other:


Showing theme doom-opera-light.


To display custom-defined sidebars, call the function org-sidebar with the arguments described in its docstring. See examples in, as well as the definitions of functions org-sidebar--todo-items and org-sidebar--upcoming-items.




Demo recorded using packages =org-sticky-header=, =org-bullets=, and theme =doom-city-lights=.

In the tree buffer, the keymap org-sidebar-tree-map is used, which is based on org-mode-map (so you can use Org keybindings to manipulate nodes), and has these additional bindings by default:

  • <S-tab>: Cycle global node visibility.
  • <tab>: Toggle visibility of child nodes.
  • <mouse-2>: Toggle visibility of child nodes.
  • <mouse-1>: Jump to heading using default jump function; or, if heading stars are clicked, toggle visibility of child nodes.
  • <return>: Jump to heading using default jump function (adding universal prefix arguments to display more subtree content, corresponding with the click-and-drag mouse events below).

Dragging-and-releasing with mouse buttons (as opposed to clicking and releasing at a single position) shows additional subtree and entry content:

  • <drag-mouse-1>: Jump to heading using default jump function, and also show all descendant headings.
  • <drag-mouse-2>: Jump to heading using default jump function, and also show all descendant headings and their entry text.

If you prefer, you may customize org-sidebar-tree-jump-fn to jump to entries in their source buffer rather than indirect buffers.


Toggle the tree sidebar.

Item sidebars

These commands display item sidebars, which display Org entries gathered with org-ql.

Key bindings: In an item sidebar buffer, these keys are bound:

  • RET, mouse-1: Jump to an item in its buffer.
  • g: Update the sidebar.
  • q: Hide the sidebar.

org-sidebar (&key buffers fns structs group super-groups)

Interactively, display the sidebars configured in org-sidebar-default-fns.

  • BUFFERS may be one or a list of buffers to display in the sidebar.
  • FNS may be one or a list of functions, each of which may return a buffer or a org-sidebar struct.
  • SIDEBARS may be one or a list of org-sidebar structs.
  • When GROUP is non-nil (interactively, with one universal prefix argument), and when SUPER-GROUPS is nil, call each function with the group keyword argument non-nil.
  • SUPER-GROUPS may be a list of groups according to org-super-agenda-groups, in which case the items in the buffers will be grouped accordingly (where applicable). Interactively, with two universal prefix arguments, the global value of org-super-agenda-groups is used.


Toggle the default item sidebars.

org-sidebar-ql (&key query buffers-files narrow group-property sort)

Display a sidebar for org-ql QUERY. Interactively, with prefix, prompt for these variables:

  • BUFFERS-FILES: A list of buffers and/or files to search.
  • NARROW: When non-nil, don’t widen buffers before searching.
  • GROUP-PROPERTY: One of the following symbols: category, parent, priority, todo.
  • SORT: One or a list of org-ql sorting functions, like date or priority.




  • Commands org-sidebar-toggle and org-sidebar-tree-toggle, which toggle the respective sidebars on/off.


Extensive refactoring and improvements.


  • Tree-view sidebar, helpful for navigating large outline trees. See documentation.


First tagged version.


This was inspired by this /r/Emacs post, which was inspired by Organized for Atom.



You can’t perform that action at this time.