Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/alphapapa/org-sidebar

A helpful sidebar for Org mode
https://github.com/alphapapa/org-sidebar

emacs org-mode

Last synced: 7 days ago
JSON representation

A helpful sidebar for Org mode

Awesome Lists containing this project

README 

        

#+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: