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:
- Install quelpa-use-package (which can be installed directly from MELPA).
- 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 examples.org, 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.
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.
Interactively, display the sidebars configured in org-sidebar-default-fns.
FNSmay be one or a list of functions, each of which should return a buffer to be displayed in a sidebar window.
Toggle the default item sidebars.
Display a sidebar for org-ql QUERY. Interactively, with prefix, prompt for these variables:
BUFFERS-FILES:Alist 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 oforg-qlsorting functions, likedateorpriority.