+TITLE: org-sidebar

[[https://melpa.org/#/org-sidebar][file:https://melpa.org/packages/org-sidebar-badge.svg]]

[[https://stable.melpa.org/#/org-sidebar][file:https://stable.melpa.org/packages/org-sidebar-badge.svg]]

This package presents helpful sidebars for Org buffers. Sidebars are customizable using [[https://github.com/alphapapa/org-ql][org-ql]] queries and [[https://github.com/alphapapa/org-super-agenda][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 :PROPERTIES: :TOC: this :END:

  • [[#installation][Installation]]
  • [[#usage][Usage]]
  • [[#changelog][Changelog]]
  • [[#notes][Notes]]

• Installation :PROPERTIES: :TOC: 0 :END:

** MELPA

If you installed from MELPA, you're done!

** Quelpa

Installing with [[https://framagit.org/steckerhalter/quelpa][Quelpa]] is easy:

1. Install [[https://framagit.org/steckerhalter/quelpa-use-package#installation][quelpa-use-package]] (which can be installed directly from MELPA).
2. Add this form to your init file:

+BEGIN_SRC elisp

(use-package org-sidebar :quelpa (org-sidebar :fetcher github :repo "alphapapa/org-sidebar"))

+END_SRC

You may find [[https://github.com/alphapapa/unpackaged.el#upgrade-a-quelpa-use-package-forms-package][this function]] helpful for updating packages with Quelpa.

• Usage :PROPERTIES: :TOC: 0 :END:

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:

• ==: Cycle global node visibility.
• ==: Toggle visibility of child nodes.
• ==: Toggle visibility of child nodes.
• ==: Jump to heading using default jump function; or, if heading stars are clicked, toggle visibility of child nodes.
• ==: 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:

• ==: Jump to heading using default jump function, and also show all descendant headings.
• ==: 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 :PROPERTIES: :TOC: 0 :END:

** 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

• [[https://github.com/darioceccoli][Dario Ceccoli]] and [[https://github.com/egh][Erik Hetzner]] ([[https://github.com/alphapapa/org-sidebar/issues/26][#26]], [[https://github.com/alphapapa/org-sidebar/pull/35][#35]]).

** 0.3.2

Fixed

• Command =org-sidebar-tree-toggle= didn't always toggle the tree sidebar off. (Fixes [[https://github.com/alphapapa/org-sidebar/issues/34][#34]]. Thanks to [[https://github.com/titaniumbones][Matt Price]] and [[https://github.com/mkb6][mkb6]] for reporting.)

** 0.3.1

Fixed

• Exclude pre-heading content from tree buffer. (Issue [[https://github.com/alphapapa/org-sidebar/issues/23][#23]]. Thanks to [[https://github.com/yuchen-lea][@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 [[#org-sidebar-tree][documentation]].

** 0.1

First tagged version.

• Notes

This was inspired by [[https://www.reddit.com/r/emacs/comments/88mtrh/emacs_org_mode_with_atom_org_mode_design/][this /r/Emacs post]], which was inspired by [[https://github.com/MattFlower/organized/][Organized for Atom]].

• License :PROPERTIES: :TOC: ignore :END:

GPLv3.

• COMMENT Config :PROPERTIES: :TOC: ignore :END:

Local Variables:

before-save-hook: org-make-toc

End: