#+TITLE: evil-org

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

Supplemental evil-mode key-bindings to Emacs org-mode.
This project is a continuation of
https://github.com/edwtjo/evil-org-mode/blob/master/evil-org.el by Edward Tjörnhammar.
From version 1.3 it was taken over by Somelauw.
See [[file:doc/changelog.org][changelog]] for a history of changes.

** Features
 - normal, visual and insert mode bindings
 - key bindings organised in key themes
 - operators like > and < to work on headings
 - text objects
 - table support
 - calendar (date selection) support
 - agenda support

** Keybindings

   [[file:doc/keythemes.org][Full overview of bindings and configuration]]

*** Quick overview

    |----------------+---------------------------|
    | key            | explanation               |
    |----------------+---------------------------|
    | gh, gj, gk, gl | navigate between elements |
    | vae            | select an element         |
    |----------------+---------------------------|

**** Headings and items

     |--------------+------------------------|
     | key          | explanation            |
     |--------------+------------------------|
     | M-ret        | insert heading         |
     | <tab>, g TAB | fold / unfold headings |
     | M-h or <<    | promote a heading      |
     | M-l or >>    | demote a heading       |
     | M-k          | move subtree up        |
     | M-j          | move subtree down      |
     | M-S-h or <aR | promote a subtree      |
     | M-S-l or >aR | demote a subtree       |
     | vaR          | select a subtree       |
     |--------------+------------------------|

**** Tables

     |-----------+--------------------------------|
     | key       | explanation                    |
     |-----------+--------------------------------|
     | (         | previous table cell            |
     | )         | next table cell                |
     | {         | beginning of table             |
     | }         | end of table                   |
     | M-h / M-l | move table column left / right |
     | M-k / M-j | move table column up / down    |
     | vae       | select table cell              |
     | vaE       | select table row               |
     | var       | select whole table             |
     |-----------+--------------------------------|

**** Agenda

     |-------------------------+-------------------------+-----------------------------------------------------------------------------------|
     | Evil key                | Emacs key               | explanation                                                                       |
     |-------------------------+-------------------------+-----------------------------------------------------------------------------------|
     | gH                      |                         | Move cursor to the top of window                                                  |
     | gM                      |                         | Move cursor to the middle of window                                               |
     | gL                      |                         | Move cursor to the bottom of window                                               |
     | <tab>, S-<return>       | <tab>                   | go to the corresponding entry at point                                            |
     | g TAB                   | <tab>                   | go to the corresponding entry at point                                            |
     | <return>                | <return>                | go to the Org mode file which contains the item at point                          |
     | M-<return>              | L                       | Display Org file and center around the item                                       |
     | <space>                 | <space>                 | scroll up                                                                         |
     | <delete> or <backspace> | <delete> or <backspace> | scroll down                                                                       |
     | j, k                    | n, p                    | next, previous line                                                               |
     | gj, gk, C-j, C-k        | N, P                    | next, previous item                                                               |
     | [, ]                    | b, f                    | previous, next week                                                               |
     | J, K                    | -, +, S-down, S-up      | down, up priority                                                                 |
     | H, L                    | S-left, S-right         | modify date to earlier, later                                                     |
     | t                       | t                       | cycle TODO keywords                                                               |
     | M-j, M-k                | M-down, M-up            | drag line forward, backward                                                       |
     | C-S-h, C-S-l            | C-S-left, C-S-right     | previous, next keyword                                                            |
     | u                       | C-_, C-/                | undo                                                                              |
     | dd                      | C-k                     | delete item                                                                       |
     | da                      | a                       | ask and archive item                                                              |
     | dA                      | $                       | archive item                                                                      |
     | ct                      | :                       | set tags                                                                          |
     | ce                      | e                       | set effort                                                                        |
     | cT                      | ;                       | set timer                                                                         |
     | i                       | i                       | insert entry in diary                                                             |
     | a                       | z                       | add note                                                                          |
     | A                       | A                       | append to agenda                                                                  |
     | C                       | k                       | capture                                                                           |
     | m                       | m                       | mark                                                                              |
     | *                       | *                       | toggle all marks                                                                  |
     | %                       | %                       | mark regexp                                                                       |
     | M                       | U                       | remove all marks                                                                  |
     | x                       | B                       | execute action on marks                                                           |
     | gr                      | r                       | refresh agenda                                                                    |
     | gR                      | g                       | refresh all agendas                                                               |
     | ZQ                      | x                       | exit agenda                                                                       |
     | ZZ                      | Q                       | quit agenda                                                                       |
     | gD                      | v                       | tweak display (deadlines, diary, follow/log-mode, entry text, grid, day/week/year |
     | ZD                      | #                       | dim blocked tasks                                                                 |
     | sc, sr, se, st, s^      | <, =, _, /, ^           | filter by category, regexp, effort, tag, top headline                             |
     | S                       | \vert                   | remove all filters                                                                |
     | ss                      | ~                       | filter/limit interactively                                                        |
     | I                       | I                       | clock in                                                                          |
     | O                       | O                       | clock out                                                                         |
     | cg                      | J                       | jump to the currently clocked in task within the agenda                           |
     | cc                      | X                       | cancel the current running clock                                                  |
     | cr                      | R                       | toggle clocktable mode in an agenda buffer                                        |
     | .                       | .                       | go to today's date                                                                |
     | gc                      | c                       | pop up calendar                                                                   |
     | gC                      | C                       | pop up date converter                                                             |
     | p                       | >                       | pop up date selector                                                              |
     | gh                      | H                       | pop up holiday calendar                                                           |
     | gm                      | M                       | pop up phases of the moon                                                         |
     | gs                      | S                       | pop up sunrise/sunset times                                                       |
     | gt                      | T                       | pop up tag list                                                                   |
     | +, -                    | [, ]                    | manipulate the query by adding a search term with positive or negative selection  |
     |-------------------------+-------------------------+-----------------------------------------------------------------------------------|

** Requirements

   - org-mode, git://orgmode.org/org-mode.git
   - evil-mode, https://github.com/emacs-evil/evil

** Installation

*** Manual installation
    #+BEGIN_SRC sh
    mkdir -p ~/.emacs.d/plugins; git clone \
    git://github.com/somelauw/evil-org-mode.git ~/.emacs.d/plugins/evil-org-mode
    #+END_SRC

**** Configuration emacs.el

    #+BEGIN_SRC emacs-lisp
    (add-to-list 'load-path "~/.emacs.d/plugins/evil-org-mode")
    (require 'evil-org)
    (add-hook 'org-mode-hook 'evil-org-mode)
    (evil-org-set-key-theme '(navigation insert textobjects additional calendar))
    (require 'evil-org-agenda)
    (evil-org-agenda-set-keys)
    #+END_SRC

    Or you can customize =evil-org-key-theme= and replace the last line by:
    #+BEGIN_SRC emacs-lisp
    (evil-org-set-key-theme)
    #+END_SRC

*** Installation by use-package
    #+BEGIN_SRC emacs-lisp
    (use-package evil-org
      :ensure t
      :after org
      :hook (org-mode . (lambda () evil-org-mode))
      :config
      (require 'evil-org-agenda)
      (evil-org-agenda-set-keys))
    #+END_SRC

    For a more elaborate setup, take a look at [[file:doc/example_config.el][this example]].

** Common issues

   In case you run Emacs in a terminal, you might find that =TAB= does not work
   as expected (being bound to =evil-jump-forward= instead of =org-tab=).
   You can add this to your configuration to get =org-tab= instead at the cost
   of losing =C-i= to jump.

   #+BEGIN_SRC emacs-lisp
   (setq evil-want-C-i-jump nil)
   #+END_SRC

** See also

   - [[https://github.com/edwtjo/evil-org-mode][evil-org-mode by edwtjo]]
     Original org-mode plugin by edwtjo from which this project was forked

   - [[https://github.com/GuiltyDolphin/org-evil][org-evil by GuiltyDolphin]]
     Alternative integration of evil and org with different keybindings

   - https://github.com/abo-abo/worf
     Not an evil plugin, but provides vim-inspired key bindings

   - https://github.com/jceb/vim-orgmode
     Org mode plugin for vim

   - http://orgmode.org/
     The official org-mode website

   - [[http://orgmode.org/orgcard.pdf]]
     A handy cheat sheet, even if using this plugin

   - https://github.com/Somelauw/evil-markdown
     Similar project for markdown code

** License

 Gnu General Public License v3.0, http://www.gnu.org/copyleft/gpl.html