spacemacs/layers/+emacs/org/README.org

Org layer

• Description
  • Features:
  • BibTeX
  • Important Note
• Install
  • Layer
  • Github support
  • Twitter Bootstrap support
  • Gnuplot support
  • Reveal.js support
  • Org-journal support
  • Hugo support
  • Different bullets
  • Project support
  • Org-brain support
  • Mode line support
• Key bindings
  • Starting org-mode
  • Toggles
  • Org-mode
  • Org with evil-org-mode
  • Tables
  • Trees
  • Element insertion
  • Links
  • Emphasis
  • Navigating in calendar
  • Capture buffers and src blocks
  • Org agenda
    • Keybindings
    • Org agenda transient state
  • Pomodoro
  • Presentation
  • Org-projectile
  • Org-journal
  • Org-brain
    • Application bindings
    • Visualization bindings

Description

This layer enables org mode for Spacemacs.

Features:

• Vim inspired key bindings are provided by evil-org-mode
• Nicer bullet via org-bullets
• A pomodoro method integration via org-pomodoro
• Presentation mode via org-present
• Insertion of images via org-download
• Project-specific TODOs via org-projectile

BibTeX

For more extensive support of references through BibTeX files, have a look at the BibTeX layer.

Important Note

Since version 0.104, spacemacs uses the org version from the org ELPA repository instead of the one shipped with emacs. Then, any org related code should not be loaded before dotspacemacs/user-config, otherwise both versions will be loaded and will conflict.

Because of autoloading, calling to org functions will trigger the loading up of the org shipped with emacs which will induce conflicts. One way to avoid conflict is to wrap your org config code in a with-eval-after-load block like this:

  (with-eval-after-load 'org
    ;; here goes your Org config :)
    ;; ....
    )

Install

Layer

To use this configuration layer, add it to your ~/.spacemacs. You will need to add org to the existing dotspacemacs-configuration-layers list in this file.

Github support

To install Github related extensions like ox-gfm to export to Github flavored markdown set the variable org-enable-github-support to t.

  (setq-default dotspacemacs-configuration-layers '(
    (org :variables org-enable-github-support t)))

Twitter Bootstrap support

To install the Twitter Boostrap extension (from ox-twbs), which enables twitter bootstrap formatted html, then set the variable org-enable-bootstrap-support to t.

  (setq-default dotspacemacs-configuration-layers '(
    (org :variables
         org-enable-bootstrap-support t)))

Gnuplot support

Org-mode support the plotting of data within tables through Gnuplot as demonstrated here; unfortunately, this is not terribly well supported on Windows at this stage. It is possible to disable the configuration of gnuplot support as usual by adding the package gnuplot to your dotspacemacs-excluded-packages variable.

Reveal.js support

To enable the export of your org file as a reveal.js presentation, set the variable org-enable-reveal-js-support to t. This will install the org-reveal extension.

  (setq-default dotspacemacs-configuration-layers
   '((org :variables org-enable-reveal-js-support t)))

In order to be able to use org-reveal, download reveal.js from its homepage and set org-reveal-js to the download path, as described in the manual. Alternatively, add the following line to each .org file you want to process:

#+REVEAL_ROOT: http://cdn.jsdelivr.net/reveal.js/3.0.0/

Org-journal support

org-journal is a simple journal management system for keeping a seperate journal file for each day inside a directory.

To install org-journal set the variable org-enable-org-journal-support to t.

  (setq-default dotspacemacs-configuration-layers '(
    (org :variables
         org-enable-org-journal-support t)))

By default journal files are stored in ~/Documents/journal/. You can override this by setting org-journal-dir in dotspacemacs/user-config

    (setq org-journal-dir "~/org/journal/")

You can change the journal file name format by altering org-journal-file-format.

    (setq org-journal-file-format "%Y-%m-%d")

Warning: setting org-journal-file-format to include a file extension like %Y-%m-%d.org breaks calender search functionality.

By default journal files are started with a first level heading (*) followed by the date formatted for the locale. If you prefer that your journal files are formatted differently you can alter org-journal-date-prefix and org-journal-date-format.

For example, to have your new journal files created with this header:

#+TITLE: Tuesday, September 06 2016

Simply define the following in dotspacemacs/user-config

    (setq org-journal-date-prefix "#+TITLE: ")
    (setq org-journal-date-format "%A, %B %d %Y")

The default entry is a second level heading (=** =) followed by a timestamp. If you start your journal files with a Title as shown above you may want to adjust entries to start at the first level heading and you may want to change or omit the timestamp.

    (setq org-journal-time-prefix "* ")
    (setq org-journal-time-format "")

Any of the org-journal settings can be configured in dotspacemacs/user-config or defined along side the layer itself.

For example:

  (setq-default dotspacemacs-configuration-layers '(
                                                    (org :variables
                                                         org-enable-org-journal-support t
                                                         org-journal-dir "~/org/journal/"
                                                         org-journal-file-format "%Y-%m-%d"
                                                         org-journal-date-prefix "#+TITLE: "
                                                         org-journal-date-format "%A, %B %d %Y"
                                                         org-journal-time-prefix "* "
                                                         org-journal-time-format "")
                                                    )

Configure org-journal with the layer

Hugo support

To install the Org exporter ox-hugo that generates Hugo-compatible Markdown plus TOML/YAML front-matter, set the variable org-enable-hugo-support to t.

  (setq-default dotspacemacs-configuration-layers '(
    (org :variables
         org-enable-hugo-support t)))

Different bullets

You can tweak the bullets displayed in the org buffer in the function dotspacemacs/user-config of your dotfile by setting the variable org-bullets-bullet-list. By default the list is set to ("◉" "○" "✸" "✿").

  (setq org-bullets-bullet-list '("■" "◆" "▲" "▶"))

You can disable the fancy bullets entirely by adding org-bullets to dotspacemacs-excluded-packages.

  (dotspacemacs-excluded-packages '(org-bullets))

Project support

Set the layer variable org-projectile-file to the filename where you want to store project-specific TODOs. If this is an absolute path, all todos will be stored in the same file (organized by project), whereas if it is just a single filename, todos will be stored in each project root.

  (setq-default dotspacemacs-configuration-layers
    '((org :variables org-projectile-file "TODOs.org")))

The TODO files are not added to the agenda automatically. You can do this with the following snippet. Note that this may have unintended consequences until this bug is fixed.

  (with-eval-after-load 'org-agenda
    (require 'org-projectile)
    (push (org-projectile-todo-files) org-agenda-files))

Org-brain support

For Emacs 25 or later, support for org-brain is included. See the org-brain package documentation for more information.

Mode line support

To temporarily enable mode line display of org clock, press SPC t m c.

To permanently enable mode line display of org clock, add this snippet to your dotspacemacs/user-config function:

  (setq spaceline-org-clock-p t)

Key bindings

Starting org-mode

Key Binding	Description
SPC a o #	org agenda list stuck projects
SPC a o /	org occur in agenda files
SPC a o a	org agenda list
SPC a o c	org capture
SPC a o e	org store agenda views
SPC a o k i	org clock in last
SPC a o k j	org jump to current clock
SPC a o k o	org clock out
SPC a o k r	org resolve clocks
SPC a o l	org store link
SPC a o m	org tags view
SPC a o o	org agenda
SPC a o s	org search view
SPC a o t	org todo list
SPC C c	org-capture

Toggles

Key Binding	Description
SPC m T e	org-toggle-pretty-entities
SPC m T i	org-toggle-inline-images
SPC m T l	org-toggle-link-display
SPC m T t	org-show-todo-tree
SPC m T T	org-todo
SPC m T V	toggle space-doc-mode a read-only view mode
SPC m T x	org-preview-latex-fragment

Org-mode

Key Binding	Description
SPC m <dotspacemacs-major-mode-leader-key>	org-ctrl-c-ctrl-c
SPC m *	org-ctrl-c-star
SPC m RET	org-ctrl-c-ret
SPC m -	org-ctrl-c-minus
SPC m '​	org-edit-special
SPC m a	org-agenda
SPC m A	org-attach
SPC m c	org-capture
SPC m C c	org-clock-cancel
SPC m C g	evil-org-recompute-clocks
SPC m C i	org-clock-in
SPC m C o	org-clock-out
SPC m C r	org-resolve-clocks
SPC m d d	org-deadline
SPC m d s	org-schedule
SPC m d t	org-time-stamp
SPC m d T	org-time-stamp-inactive
SPC m e e	org-export-dispatch
SPC m e m	send current buffer as HTML email message
SPC m l	org-open-at-point
SPC m L	org-shiftright
SPC m H	org-shiftleft
SPC m K	org-shiftup
SPC m J	org-shiftdown
SPC m C-S-l	org-shiftcontrolright
SPC m C-S-h	org-shiftcontrolleft
SPC m C-S-j	org-shiftcontroldown
SPC m C-S-k	org-shiftcontrolup
SPC s j	spacemacs/jump-in-buffer (jump to a heading)

Org with evil-org-mode

Please see the evil-org documentation for additional instructions on customizing evil-org-mode.

Key Binding	Description
gj / gk	Next/previous element (heading)
gh / gl	Parent/child element (heading)
gH	Root heading
ae	Element text object
ar	Subtree text object
M-j / M-k	Move heading
M-h / M-l	Promote or demote heading
M-J / M-K	Move subtree
M-H / M-L	Promote or demote subtree
>> / <<	Promote or demote heading

If the layer variable org-want-todo-bindings is true, the following bindings are also available.

Key Bindings	Description
t	Cycle TODO state of current heading
T	Insert new TODO heading
M-t	Insert new TODO sub-heading

Tables

Key Binding	Description
SPC m t a	Align the table at point by aligning all vertical bars
SPC m t b	Blank the current table field or active region
SPC m t c	Convert from org-mode table to table.el and back
SPC m t d c	Delete a column from the table
SPC m t d r	Delete the current row or horizontal line from the table
SPC m t e	Replace the table field value at the cursor by the result of a calculation
SPC m t E	Export table to a file, with configurable format
SPC m t h	Go to the previous field in the table
SPC m t H	Move column to the left
SPC m t i c	Insert a new column into the table
SPC m t i h	Insert a horizontal-line below the current line into the table
SPC m t i H	Insert a hline and move to the row below that line
SPC m t i r	Insert a new row above the current line into the table
SPC m t I	Import a file as a table
SPC m t j	Go to the next row (same column) in the current table
SPC m t J	Move table row down
SPC m t K	Move table row up
SPC m t l	Go to the next field in the current table, creating new lines as needed
SPC m t L	Move column to the right
SPC m t n	Query for a size and insert a table skeleton
SPC m t N	Use the table.el package to insert a new table
SPC m t p	Plot the table using org-plot/gnuplot
SPC m t r	Recalculate the current table line by applying all stored formulas
SPC m t s	Sort table lines according to the column at point
SPC m t t f	Toggle the formula debugger in tables
SPC m t t o	Toggle the display of Row/Column numbers in tables
SPC m t w	Wrap several fields in a column like a paragraph

Trees

Key Binding	Description
gj / gk	Next/previous element (heading)
gh / gl	Parent/child element (heading)
gH	Root heading
ae	Element text object
ar	Subtree text object
M-j / M-k	Move heading
M-h / M-l	Promote or demote heading
M-J / M-K	Move subtree
M-H / M-L	Promote or demote subtree
>> / <<	Promote or demote heading
TAB	org-cycle
SPC m s a	org-archive-subtree
SPC m s b	org-tree-to-indirect-buffer
SPC m s l	org-demote-subtree
SPC m s h	org-promote-subtree
SPC m s k	org-move-subtree-up
SPC m s j	org-move-subtree-down
SPC m s n	org-narrow-to-subtree
SPC m s N	widen narrowed subtree
SPC m s r	org-refile
SPC m s s	show sparse tree
SPC m s S	sort trees

Element insertion

Key Binding	Description
SPC m i d	org-insert-drawer
SPC m i D s	Take screenshot
SPC m i D y	Yank image url
SPC m i e	org-set-effort
SPC m i f	org-insert-footnote
SPC m i H	org-insert-heading-after-current
SPC m i h	org-insert-heading
SPC m i K	spacemacs/insert-keybinding-org
SPC m i l	org-insert-link
SPC m i p	org-set-property
SPC m i s	org-insert-subheading
SPC m i t	org-set-tags

Links

Key Binding	Description
SPC m x o	org-open-at-point

Emphasis

Key Binding	Description
SPC m x b	make region bold
SPC m x c	make region code
SPC m x i	make region italic
SPC m x r	clear region emphasis
SPC m x s	make region strike-through
SPC m x u	make region underline
SPC m x v	make region verbose

Navigating in calendar

Key Binding	Description
M-l	One day forward
M-h	One day backward
M-j	One week forward
M-k	One week backward
M-L	One month forward
M-H	One month backward
M-J	One year forward
M-K	One year backward

Capture buffers and src blocks

org-capture-mode and org-src-mode both support the confirm and abort conventions.

Key Binding	Description
SPC m <dotspacemacs-major-mode-leader-key>	confirm in org-capture-mode
SPC m '​	confirm in org-src-mode
SPC m c	confirm
SPC m a	abort
SPC m k	abort
SPC m r	org-capture-refile in org-capture-mode

Org agenda

Keybindings

The evilified org agenda supports the following bindings:

Key Binding	Description
M-SPC or s-M-SPC	org-agenda transient state
SPC m a	org-agenda
SPC m C c	org-agenda-clock-cancel
SPC m C i	org-agenda-clock-in
SPC m C o	org-agenda-clock-out
SPC m C p	org-pomodoro (if package is used)
SPC m d d	org-agenda-deadline
SPC m d s	org-agenda-schedule
SPC m i e	org-agenda-set-effort
SPC m i p	org-agenda-set-property
SPC m i t	org-agenda-set-tags
SPC m s r	org-agenda-refile
M-j	next item
M-k	previous item
M-h	earlier view
M-l	later view
gr	refresh
gd	toggle grid
C-v	change view
RET	org-agenda-goto
M-RET	org-agenda-show-and-scroll-up

Org agenda transient state

Use M-SPC or s-M-SPC in an org agenda buffer to activate its transient state. The transient state aims to list the most useful org agenda commands and visually organize them by category. The commands associated with each binding are listed bellow.

Keybinding	Description	Command
Entry
ht	set status	org-agenda-todo
hk	kill	org-agenda-kill
hR	refile	org-agenda-refile
hA	archive	org-agenda-archive-default
h:	set tags	org-agenda-set-tags
hp	set priority	org-agenda-priority
Visit entry
SPC	in other window	org-agenda-show-and-scroll-up
TAB	& go to location	org-agenda-goto
RET	& del other windows	org-agenda-switch-to
o	link	link-hint-open-link
Filter
ft	by tag	org-agenda-filter-by-tag
fr	refine by tag	org-agenda-filter-by-tag-refine
fc	by category	org-agenda-filter-by-category
fh	by top headline	org-agenda-filter-by-top-headline
fx	by regexp	org-agenda-filter-by-regexp
fd	delete all filters	org-agenda-filter-remove-all
Date
ds	schedule	org-agenda-schedule
dS	un-schedule	org-agenda-schedule
dd	set deadline	org-agenda-deadline
dD	remove deadline	org-agenda-deadline
dt	timestamp	org-agenda-date-prompt
+	do later	org-agenda-do-date-later
-	do earlier	org-agenda-do-date-earlier
Toggle
tf	follow	org-agenda-follow-mode
tl	log	org-agenda-log-mode
ta	archive	org-agenda-archives-mode
tr	clock report	org-agenda-clockreport-mode
td	diaries	org-agenda-toggle-diary
View
vd	day	org-agenda-day-view
vw	week	org-agenda-week-view
vt	fortnight	org-agenda-fortnight-view
vm	month	org-agenda-month-view
vy	year	org-agenda-year-view
vn	next span	org-agenda-later
vp	prev span	org-agenda-earlier
vr	reset	org-agenda-reset-view
Clock
cI	in	org-agenda-clock-in
cO	out	org-agenda-clock-out
cq	cancel	org-agenda-clock-cancel
cj	jump	org-agenda-clock-goto
Other
gr	reload	org-agenda-redo
.	go to today	org-agenda-goto-today
gd	go to date	org-agenda-goto-date

Pomodoro

Key Binding	Description
SPC m C p	starts a pomodoro

Presentation

org-present must be activated explicitly by typing: SPC SPC org-present

Key Binding	Description
h	previous slide
l	next slide
q	quit

Org-projectile

Key Binding	Description
SPC a o p	Capture a TODO for the current project
SPC u SPC a o p	Capture a TODO for any given project (choose from list)
SPC p o	Go to the TODOs for the current project

Org-journal

Key Binding	Description
SPC a o j j	New journal entry
SPC a o j s	Search journal entries

Journal entries are highlighted in the calendar. The following key bindings are available for calendar-mode for navigating and manipulating the journal.

Key Binding	Description
SPC m r	Read journal entry
SPC m i	Insert journal entry for date
SPC m n	Next journal entry
SPC m p	Previous journal entry
SPC m s	Search all journal entries
SPC m w	Search calendar week journal entries
SPC m m	Search calendar month journal entries
SPC m y	Search calendar year journal entries

While viewing a journal entry in org-journal-mode the following key bindings are available.

Key Binding	Description
SPC m j	New journal entry
SPC m p	Previous journal entry
SPC m n	Next journal entry

Org-brain

Application bindings

Key Binding	Description
SPC a o b	Visualize an org-brain entry

Visualization bindings

Key Binding	Description
j / TAB	Goto next link
k / S-TAB	Goto previous link
c	Add child
p	Add parent
l	Add resource link
C-y	Paste resource link
a	Add resource attachment
o	Open and edit the visualized entry
f	Find/visit another entry to visualize
r	Rename this, or another, entry