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

README.org

org-sidebar

https://melpa.org/packages/org-sidebar-badge.svg

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.

images/screenshot.png

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

images/tree2.gif

Contents

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:

images/sidebar-with-tree.png

Showing theme doom-one-light.

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

images/tree-and-item-sidebars.png

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

images/tree.gif

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 (&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.

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.

Changelog

0.3-pre

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.

You can’t perform that action at this time.