Table of Contents

Org layer

Table of ContentsClose


1 Description

This layer enables org mode for Spacemacs.

1.1 Features:

2 BibTeX

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

3 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 :)
  ;; ....

Please also note that everything described here only applies if you install this layer instead of manually loading org as separate emacs package.

If this is not done you will encounter a lot of unbind key exceptions while working with org. More details can be found here.

4 Install

4.1 Layer

To use this configuration layer: in the main Spacemacs configuration file (~/.spacemacs), to the existing dotspacemacs-configuration-layers list add the org entry.

4.2 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)))

4.3 Twitter Bootstrap support

To enable the export to Twitter Bootstrap-formatted HTML - set the variable org-enable-bootstrap-support to t. This would install the ox-twbs extension.

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

4.4 Gnuplot support

Org-mode supports the plotting of data within tables through Gnuplot as demonstrated here.

Unfortunately, this is not terribly well supported on Windows, at this stage. To disable the configuration of gnuplot support - add the gnuplot package to your dotspacemacs-excluded-packages variable.

4.5 Reveal.js support

To enable the export of org files as a reveal.js presentation - set the variable org-enable-reveal-js-support to t. This would install the org-re-reveal Emacs extension.

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

Then the extension needs to be pointed to the reveal.js itself. So download reveal.js and point org-re-reveal-root to the path, as it described in the manual.

Alternatively, add the following line to each .org file you want to process:


4.6 Org-journal support

org-journal is a simple journal management system that:

  • Keeps a separate journal file for each day inside a directory
  • New daily file would always migrate entries with chosen TODO states
  • Has journal encryption functionality
  • Easily integrates with org-agenda and Emacs calendar, iCalendar, allows scheduling
  • Easily integrates with org-capture

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/. To override this - set org-journal-dir variable in the dotspacemacs/user-config:

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

To change the journal file name format - alter org-journal-file-format:

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

Warning: setting org-journal-file-format to include a file extension like would break the calendar search functionality.

By default, journal files are started with a first level heading (*) followed by the date in the form set by locale. To format journal files differently:

  • alter org-journal-date-prefix and org-journal-date-format. For example, to have new journal files created with this header:

    #+TITLE: Tuesday, September 06 2016
  • 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 alongside 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 "")

4.7 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)))

4.8 Trello support

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

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

4.9 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))

4.10 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 "")))

The TODO files are not added to the agenda automatically. You can do this with the following snippet.

(with-eval-after-load 'org-agenda
  (require 'org-projectile)
  (mapcar '(lambda (file)
                 (when (file-exists-p file)
                   (push file org-agenda-files)))

4.11 Org-brain support

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

4.12 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)

4.13 Sticky header support

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

(setq-default dotspacemacs-configuration-layers '(
  (org :variables
       org-enable-sticky-header t)))

4.14 Epub support

To install the Org exporter ox-epub that generates e-book file format epub, set the variable org-enable-epub-support to t.

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

4.15 Jira support

To bring Jira and OrgMode together over org-jira set the variable org-enable-jira-support to t.

(setq-default dotspacemacs-configuration-layers '(
  (org :variables
       org-enable-jira-support t
       jiralib-url "")))

If you would like to avoid being prompted for your login and password each time you connect, add your authentication credentials to ~/.authinfo.gpg or ~/.authinfo:

machine login password yourPassword port 443

5 Key bindings

5.1 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 f i org feed goto inbox
SPC a o f u org feed update all
SPC a o C c org cancel clock
SPC a o C g org goto last clocked-in clock (go to specific recent clock with SPC u)
SPC a o C i org clock in
SPC a o C I org clock in last
SPC a o C j org jump to current clock
SPC a o C o org clock out
SPC a o C 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

5.2 Toggles

Key binding Description
SPC m T c org-toggle-checkbox
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

5.3 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 d Temporarily show clock times for current file
SPC m C e org-evaluate-time-range
SPC m C g org-clock-goto
SPC m C i org-clock-in
SPC m C I org-clock-in-last
SPC m C j Jump to the current clock
SPC m C o org-clock-out
SPC m C R Insert clock report
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 f i org-feed-goto-inbox
SPC m f u org-feed-update-all
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)

5.4 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

5.5 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 f Show table field info
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

5.6 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 Toggle archive tag for subtree
SPC m s A Archive subtree
SPC m s b org-tree-to-indirect-buffer
SPC m s d org-cut-subtree
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

5.7 Element insertion

Key binding Description
C-RET Insert heading at end of current subtree
C-S-RET Insert TODO heading at end of current subtree
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
SPC m i H org-insert-heading-after-current
SPC m i i org-insert-item
SPC m i K spacemacs/insert-keybinding-org
SPC m i l org-insert-link
SPC m i L insert URL with its page title from clipboard
SPC m i n org-add-note
SPC m i p org-set-property
SPC m i s org-insert-subheading
SPC m i t org-set-tags

5.9 Babel / Source Blocks

Key binding Description
SPC m b . Enter Babel Transient State
SPC m b a org-babel-sha1-hash
SPC m b b org-babel-execute-buffer
SPC m b c org-babel-check-src-block
SPC m b d org-babel-demarcate-block
SPC m b e org-babel-execute-maybe
SPC m b f org-babel-tangle-file
SPC m b g org-babel-goto-named-src-block
SPC m b i org-babel-lob-ingest
SPC m b I org-babel-view-src-block-info
SPC m b j org-babel-insert-header-arg
SPC m b l org-babel-load-in-session
SPC m b n org-babel-next-src-block
SPC m b o org-babel-open-src-block-result
SPC m b p org-babel-previous-src-block
SPC m b r org-babel-goto-named-result
SPC m b s org-babel-execute-subtree
SPC m b t org-babel-tangle
SPC m b u org-babel-goto-src-block-head
SPC m b v org-babel-expand-src-block
SPC m b x org-babel-do-key-sequence-in-edit-buffer
SPC m b z org-babel-switch-to-session
SPC m b Z org-babel-switch-to-session-with-code

5.9.1 Org Babel Transient State

Use SPC m b . to enter a transient state for quick source block navigation and execution. During that state, the following bindings are active:

Key binding Description
' edit source block
e execute source block
g jump to named source block
j jump to next source block
k jump to previous source block
z recenter buffer in window
q leave transient state

5.10 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 verbatim
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

5.12 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

5.13 Org agenda

5.13.1 Key bindings

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

5.13.2 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.

Key binding Description Command
h: set tags org-agenda-set-tags
hA archive org-agenda-archive-default
ht set status org-agenda-todo
hk kill org-agenda-kill
hp set priority org-agenda-priority
hR refile org-agenda-refile
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
fc by category org-agenda-filter-by-category
fd delete all filters org-agenda-filter-remove-all
fh by top headline org-agenda-filter-by-top-headline
fr refine by tag org-agenda-filter-by-tag-refine
ft by tag org-agenda-filter-by-tag
fx by regexp org-agenda-filter-by-regexp
+ do later org-agenda-do-date-later
- do earlier org-agenda-do-date-earlier
dd set deadline org-agenda-deadline
dD remove deadline org-agenda-deadline
ds schedule org-agenda-schedule
dS un-schedule org-agenda-schedule
dt timestamp org-agenda-date-prompt
ta archive org-agenda-archives-mode
tc clocking issues org-agenda-show-clocking-issues
td diaries org-agenda-toggle-diary
tf follow org-agenda-follow-mode
tl log org-agenda-log-mode
tr clock report org-agenda-clockreport-mode
vd day org-agenda-day-view
vm month org-agenda-month-view
vn next span org-agenda-later
vp prev span org-agenda-earlier
vr reset org-agenda-reset-view
vt fortnight org-agenda-fortnight-view
vw week org-agenda-week-view
vy year org-agenda-year-view
cI in org-agenda-clock-in
cj jump org-agenda-clock-goto
cO out org-agenda-clock-out
cq cancel org-agenda-clock-cancel
. go to today org-agenda-goto-today
gd go to date org-agenda-goto-date
gr reload org-agenda-redo

5.14 Pomodoro

Key binding Description
SPC m C p starts a pomodoro

5.15 Presentation

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

Key binding Description
h previous slide
l next slide
q quit

5.16 Helm-org-rifle

Key binding Description
SPC a o r Search org files for keywords and headings

5.17 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

5.18 Org-journal

Key binding Description
SPC a o j j New journal entry
SPC u SPC a o j j Open today's journal without adding a new 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 i Insert journal entry for date
SPC m m Search calendar month journal entries
SPC m n Next journal entry
SPC m p Previous journal entry
SPC m r Read journal entry
SPC m s Search all journal entries
SPC m w Search calendar week 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 n Next journal entry
SPC m p Previous journal entry

5.19 Org-brain

5.19.1 Application bindings

Key binding Description
SPC a o B v Visualize an org-brain entry
SPC a o B a Go to the org-brain agenda

5.19.2 org-mode bindings

Key binding Description
SPC m B a c Add child
SPC m B a h Add headline child
SPC m B a f Add friend
SPC m B a p Add parent
SPC m B a r Add resource
SPC m B g g Go to an org-brain entry
SPC m B g c Go to child
SPC m B g f Go to friend
SPC m B g p Go to parent
SPC m B R Refile entry
SPC m B x Delete entry
SPC m B v Visualize an org-brain entry

5.19.3 Visualization bindings

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

5.20 Org-jira

Key binding Description
SPC a o J p g Get projects list
SPC a o J i b Open the current issue in a WWW browser
SPC a o J i g Get issues
SPC a o J i h Get only head of issues
SPC a o J i f Get only head of issues from filter
SPC a o J i u Update an issue at point
SPC a o J i w Progress an issue at point
SPC a o J i r Refresh an issue at point
SPC a o J i c Create an issue at point
SPC a o J i y Copy current issue key
SPC a o J s c Create a subtask
SPC a o J s g Get subtasks
SPC a o J c u Update the comment at point or add a new comment
SPC a o J t j Convert the TODO item at point to a Jira ticket

Author: root

Created: 2020-01-25 Sat 15:22