alphapapa / org-sidebar

A helpful sidebar for Org mode

org-sidebar

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:

Contents

• Installation
• Usage
• Changelog
• Notes

Installation

MELPA

If you installed from MELPA, you’re done!

Quelpa

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.

Usage

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

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.

Advanced

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

Commands

org-sidebar-tree

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.

org-sidebar-tree-toggle

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 (fns)

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

• FNS may be one or a list of functions, each of which should return a buffer to be displayed in a sidebar window.

org-sidebar-toggle

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.

org-sidebar-backlinks

Show sidebar with entries that link to the current entry. The entry must have an ID or CUSTOM_ID property; links to the heading text are not found. Note that searching for links to entries that have both ID and CUSTOM_ID properties set is much slower than searching for links to entries with just one of those properties.

Changelog

0.5-pre

Org v9.6 or later is now required.

0.4

Additions

• Option org-sidebar-window-after-display-hook.

Changes

• Use org-ql-view for sidebar buffers instead of bespoke implementation.
• org-sidebar now accepts only a FNS argument, and sidebars are not defined with structs. Some functionality may have been temporarily lost due to this refactoring. Users may wish to use version 0.3 until it is restored.
• Set mode-line-format as a window parameter in sidebar windows rather than setting the buffer-local variable in sidebar buffers.

Fixes

• TAB binding in org-sidebar-tree-map.

Thanks

• Dario Ceccoli and Erik Hetzner (#26, #35).

0.3.2

Fixed

• Command org-sidebar-tree-toggle didn’t always toggle the tree sidebar off. (Fixes #34. Thanks to Matt Price and mkb6 for reporting.)

0.3.1

Fixed

• Exclude pre-heading content from tree buffer. (Issue #23. Thanks to @yuchen-lea for reporting.)

0.3

Added

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

0.2

Extensive refactoring and improvements.

Added

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

0.1

First tagged version.

Notes

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

License

GPLv3.