Org-mode Quick Guide

Summarized guide for features I commonly use, for quick reference.

References

This section is first, because

  1. My notes are incomplete and only focus on a few useful features I’ve managed to find. orgmode is huge.
  2. To put a disclaimer that I may have introduced errors while writing these notes.

Here goes

  1. The primary site.
  2. The online docs are here

For ready reference, here is the Emacs manual.

May the force multiply with you!

This document (and most of this site) has been written in orgmode. Page rendered with the help of Hugo using the built-in org-mode publishing support.

Document Structure

Visibility cycling

With the cursor at the top of the node - the lines with the *-s, the following work.

Shortcut Action
TAB Cycle visibility of current node
S-TAB / C-u TAB Cycle visibility of all nodes
C-u C-u C-u TAB show all, including drawers

Motion

Shortcut Action
C-c C-n Next heading
C-c C-p Previous heading
C-c C-f Next heading same level
C-c C-b Previous heading same level
C-c C-u Backward to higher level heading
C-c C-j Navigate with outline and jump

Plain lists

Within lists (ordered or unordered), the short-cuts work differently.

  • Lists start with ‘-’, ‘+’ or a number followed by a dot or a ‘)’.
  • Ordered lists with ‘1.’ or ‘1’ or ‘1)’
  • Use ‘Shift-<arrow-key>’ to change the list beginning character style
  • Description lists use ‘::’ to separate the term from the description

Structure editing

M-RET
Insert new heading at same level as current
M-S-RET
If heading, insert new TODO entry at same level as current heading
M-S-RET
If a list item, insert a new item with a checkbox
  • Like this.
  • Checkboxes can be toggled with C-c C-c
M-LEFT/RIGHT
Promote/demote current heading by one level
M-S-LEFT/RIGHT
Promote/demote current subtree by one level
M-UP/DOWN
Move subtree up/down
M-S-UP/DOWN
Move item up/down (swap with previous/next subtree at same level). Renumbering is automatic in ordered lists.
C-c C-w
Refile entry/region to a different location
C-x n s/w
Narrow buffer to current subtree / widen it again

Tables

Tables are tables, and more! They even support spreadsheet like calculations in connection with the Emacs ‘calc’ package. Any line with the ‘|’ as the first non-whitespace character is considered part of a table. ‘|’ is also a column separator. Example:

Shortcut Action
TAB/ C-c C-c / RET Realign when inside table
TAB Insert new row when in the last column of the last row, or move to the next field
RET Move to the next row
C-c PIPE (Note: PIPE is PIPE character) Create a new table.
M-RIGHT/LEFT Move current column to left/right
M-S-LEFT Kill current column
M-S-RIGHT Insert new column to the left of the cursor position
M-S-UP Kill current row or horizontal line
M-UP/DOWN Move current row up/down
M-S-DOWN Insert a new row above the current row.
C-c - Insert a horizontal line below current row.
C-c RET Insert a horizontal line below current row and move cursor into the row below that line.
C-c ^ Sort the table lines in the region.

If a line starts with `|-`, then it inserts a row separator, which automatically re-aligns on the next TAB. For further detailed reading, see Chapter 3 - Tables

Format

[ [ link ] [optional description ] ] (No spaces between brackets)

[ [#some-id] ] links to the entry with the CUSTOM_ID property set to ‘some-id’

  • http://
  • file:/…
  • /filesystem/path
  • (relative path)
  • docview:/Users/jaju/orgguide.pdf::NNN (open file in doc-view mode at page NNN)
  • id: ABCD-EFGH Link to heading by ID
  • mailto:someemail@domain
  • irc:/irc.com/#emacs/jaju
Shortcut Action
C-c l Store a link to the current location under the cursor
C-c C-l Insert a link at the current location.
C-u C-c C-l Insert a link to a file (using filename completion)
C-c C-o Open link at point (can use mouse too.)
C-c & Jump back to a recorded position. Positions are recorded either by following internal links, or using C-c %

TODO Items

Short-cut Action
C-c C-t Rotate the TODO state of the current item
S-RIGHT/LEFT Select the following/preceding TODO state (similar to cycling)
C-c / t View TODO items in a sparse tree
C-c a t View the global TODO list
S-M-RET Insert a new TODO entry below the current line

Changing a TODO state can also trigger tag changes. The docstring of org-todo-state-tags-triggers has more details.

TODO Multi-state workflows

  • Set the org-todo-keywords list to the new sequence you want
  • You can even use different sets of TODO keywords-sets in parallel for different kinds of workflows
  • When you (setq org-log-done ’time), you can keep track of when a task was finished.
  • When you (setq org-log-done ’note), you will be prompted for a note which allows you to store a ‘Closing Note’
  • Breaking down a large TODO into manageable subtasks
    • Quite simple. Create an outline tree below a TODO.
    • Insert ‘[0/0]’ or ‘[0%]’ anywhere in the headline to track % or fraction completed.
  * TODO This is a sample todo which is broken down into tasks [1/2] [50%]
  ** TODO This item is open
  ** DONE This item is closed
     CLOSED: [2012-11-16 Fri 22:31]
  * TODO Another todo with lists of items [0/3]
   - [ ] This is subtask ONE [0/2]
     - [ ] Item 1-1
     - [ ] Item 1-2
   - [ ] This is subtask TWO [0/0]
   - [ ] This is subtask THREE [0%]

Prioritizing TODO items

Add a Priority Cookie to the headline of a TODO item. There are three priorities by default - A, B and C.

  * TODO [#A] A permanent high-priority todo.
Shortcut Action
C-c , Set the priority of the current headline
S-UP/DOWN Increase/decrease priority of current headline

Further reading

Tags important

Assigning tags to headlines is an excellent way to implement labels and contexts for cross-correlating information. Every headline can contain a list of tags; they occur at the end of the headline. Tags are normal words containing letters, numbers, ‘_’ and ‘@’. Tags must be preceded and followed by a single colon. E.g., ‘:work:’. Several tags can be specified, as in ‘:work:urgent:’.

Inheritance

Tags are hierarchical. All subheadings inherit tags from parents.

#+FILETAGS: :TOP:LEVEL:TAGS:

Setting tags

Shortcut Action
M-TAB Offer completion of tags
C-c C-q Enter new tags for the current headline

Tags that should be available in a file can be set with lines like

Tag Searches

Once a system of tags has been set up, it can be used to collect related information into special lists

Shortcut Action
C-c \
C-c / m Create a sparse tree with all headlines matching a tags search
C-c a m Create a global list of tag matches from all agenda files
C-c a M Create a global list of tag matches from all agenda files, but check only TODO items and force checking subitems

Further reading

Sacha Chua’s article about tagging in Org-mode Chapter 6 of the manual

Properties

Properties are key-value pairs associated with an entry. They live in a special drawer with the name PROPERTIES. Each property is specified on a single line, with the key (surrounded by colons) first, and the value after it.

Shortcut Action
C-c C-x p Set a property. This prompts for a property name and value.
C-c C-c d Remove a property from the current entry.

Drawers

A drawer is a sub-note, and can be inserted at a point using “C-c C-x d” It’s an item you normally do not want to see. A drawer can be named with any word, and can contain arbitrarily long texts.

  :DRAWER:
  This is a sample drawer
  :END:

Timestamps

A timestamp is a specification of a date in a special format <YYYY-MM-DD Day> or <YYYY-MM-DD Day HH:MM> or <YYYY-MM-DD Day HH:MM-HH:MM> You can set repeat intervals (of weeks, days, or months, years etc.) by appending one of +1d, +1w, +10m, +2y etc. to the timestamp. You can also have a range like <YYYY-MM-DD Day>–<YYYY-MM-DD Day>

Shortcut Action Description
C-c . Prompt for a date and insert a corresponding timestamp. At an existing timestamp, you are prompted for modification.
C-c ! Like C-c ., but an inactive timestamp.
S-LEFT/RIGHT Change date at cursor by a day.
S-UP/DOWN Change the item under the cursor in a timestamp. The cursor can be on year, month, day, hour, minute.

Time planning

A timestamp may be preceded by a special keyword to facilitate planning

Shortcut Action
C-c C-d Insert ‘DEADLINE’. When looking at the agenda, DEADLINE-s will show up. The range can be controlled by setting the org-deadline-warning-days’ value appropriately.
C-c C-s Inserts ‘SCHEDULED’ which means work to start on that date.

Clocking work time

Org mode allows you to clock the time you spend on specific tasks in a project.

Shortcut Action
C-c C-x C-i Start the clock on the current item. When called with a C-u prefix argument, select the task from a list of recently clocked tasks.
C-c C-x C-o Stop the clock
C-c C-x C-e Update the effort estimate for the current clock task.
C-c C-x C-x Cancel the current clock.
C-c C-x C-j Jump to the entry that contains the currently running clock. C-u prefix for the usual modded meaning.
C-c C-x C-r Insert a dynamic block containing a clock report as an org-mode table into the current file! When at an existing table, update!
C-c C-c Update the dynamic block at point. The cursor should be in the #+BEGIN line of the dynamic blcok.

Further reading

Chapter 8 of the manual Charles Cave’s Date and Time tutorial Bernt Hansen’s clocking workflow

Capture - Refile - Archive

Capture

Capture anything with little interruption to your workflow. Org lets you define templates for new entries and associate them with different targets for storing notes. You can set up a capture location. For example, to set a default target file for notes, and define a global key for capturing new stuff: (setq org-default-notes-file (concat org-directory “/notes.org”) (define-key global-map “\C-cc” ‘org-capture)

Shortcut Action
C-c c Start a capture process.
C-c C-c Once done capturing the information, return to the original place of work.
C-c C-w Finalize by moving the entry to a refile location
C-c C-k Abort the capture process and return to the previous state.

Capture templates

You can use templates to generate different types of capture notes, and to store them in different places. For example, if you would like to store new tasks under a heading “Tasks” in the file “TODO.org,” and journal entries in a date tree in ‘journal.org’ you could use:

  (setq org-capture-templates '(("t" "Todo" entry (file+headline "~/.org/gtd.org" "Tasks") "* TODO %?\n %i\n %a")
  ("j" "Journal" entry (file+datetree "~/.org/journal.org") "* %?\nEntered on %U\n %i\n %a")))

Refiling notes

Archiving

TODO Agenda Views incomplete

  • Agenda files
  • The agenda dispatcher
  • The built-in agenda views
  • Commands in the agenda buffer
  • Custom agenda views

Markup for rich export incomplete

Structural markup elements

  • Document title
  • Headings and sections
  • Table of contents
  • Paragraphs, line breaks, and quoting
  • Emphasis and monospace
  • Comment lines

Images and Tables

Literal examples urgent

  (defn foo []
    (reduce + (range 10)))

You can edit the above block in a buffer of its own with “C-c ‘” - and exit the buffer with the same shortcut.

Exporting urgentincomplete

The exporter recognizes special lines in the buffer which provide additional information. These lines can be anywhere in the file. The whose set of lines can be inserted into the buffer with the shortcut: C-c C-e t (like below)

#+TITLE:     orgguide.org
#+AUTHOR:    Ravindra Jaju
#+EMAIL:     someone@somedomain.com
#+DATE:      2012-11-17 Sat
#+DESCRIPTION:
#+KEYWORDS:
#+LANGUAGE:  en
#+OPTIONS:   H:3 num:t toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t <:t
#+OPTIONS:   TeX:t LaTeX:t skip:nil d:nil todo:t pri:nil tags:not-in-toc
#+INFOJS_OPT: view:nil toc:nil ltoc:t mouse:underline buttons:0 path:http://orgmode.org/org-info.js
#+EXPORT_SELECT_TAGS: export
#+EXPORT_EXCLUDE_TAGS: noexport
#+LINK_UP:
#+LINK_HOME:
#+XSLT:

Technical Content

LaTeX

MathJax

Aligning

A quick great set of examples at Aligning LaTeX content.

Working with source code urgentincomplete

You can use org-babel to do literate programming. Write your code and the surrounding text in a single org-document. And export the code, or generate rich documentation, or even capture output of running the code in an evaluation-engine right within the org document.

Some sample code blocks - they are surrounded by the BEGIN_SRC and END_SRC tags.

(defn foo [x]
  (+ 2 x))

import scala.util.parsing.combinator._

class Arith extends JavaTokenParsers {
  def expr: Parser[Any] = term ~ rep("+" ~ term | "-" ~ term)

  def term: Parser[Any] = factor ~ rep("*" ~ factor | "/" ~ factor)

  def factor: Parser[Any] = floatingPointNumber | "(" ~ expr ~ ")"
}

An interesting case is when you capture data for different scenarios in a table, and would like to run that table (individual rows, columns, or some combination) through code and capture the output (again in a table format, for easy visual correlation). Use the NAME attribute on the table and provide a unique name, like so

#+NAME: bin-table

X Y
0 0
0 1
1 0
1 1

Now, use the following on kind of BEGIN_SRC directive

#+BEGIN_SRC clojure :results value pp :var XY=bin-table :colnames y

On evaluation, the table defined above is supplied as input at the XY location in the code.

(defn mapply [f vals]
  (map #(apply f %) vals))

(defn add-my-numbers [x y]
  (+ x y))

(mapply add-my-numbers XY)
(0 1 1 2)

If we have another table with more columns, some of which we’d like to ignore

  #+NAME: bin-table-more

W X Y Z
0 1 2 3
4 5 6 7
8 9 10 11

We’d like to add columns X and Y for each row.

#+BEGIN_SRC clojure :results value pp :var XY=bin-table-more[1:3,1:2] :colnames y
(mapply add-my-numbers XY)
(3 11 19)

Read more about passing vars to code-blocks here