Org Guide

Quick Org-mode Guide. When you do not wish to read long docs.

The online guide is at this link.

Document Structure

Visibility cycling

  • TAB
  • S-TAB and C-u TAB
  • C-u C-u C-u TAB (show all, including 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.

Motion

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

Structure editing

M-RET
Insert new heading at same level as current
M-S-RET
Insert new TODO entry at same level as current heading
M-LEFT/RIGHT
Promote/demote current heading by one level
M-S-LEFT/RIGHT
Promote/demote current subtree by one level
M-S-UP/DOWN
Move subtree up/down (swap with previous/next subtree at same level)
C-c C-w
Refile entry/region to a different location
C-x n s/w
Narrow buffer to current subtree / widen it again
(no term)
Plain lists
  • Within lists (ordered or unordered), the short-cuts work differently.
  • Lists start with '-', '+' or '*'.
  • Unordered lists with '1.' or '1' or '1)'
  • Description lists use '::' to separate the term from the description
M-RET
Insert new item at current level.
M-S-RET
Insert a new item with a checkbox
  • [ ] Like this.
  • Checkboxes can be toggled with C-c C-c
M-S-UP/DOWN
Move item including subitems up/down. Renumbering is automatic in ordered lists.
M-LEFT/RIGHT
Decrease/increase indentation level.
C-c C-c
If there is a checkbox, toggle state.
C-C
Cycle entire list level through the different itemize/enumerate bullets (try it right here!)
Footnotes
This is any paragraph that is started by a footnote marker in square brackets in column 0 (no indentation allowed.) The footnote reference is simply the marker in square brackets, inside text.
C-c C-x f
The footnote action command. When cursor is on a footnote reference, jump to the definition. And when at a definition, jump to the (first) reference. Otherwise, create a new footnote.
C-c C-c
Jump between definition and reference

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:

Short-cut 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. Further reading at

Hyperlinks

  • Format [ [ link ] [optional description ] ] (No spaces between brackets)
  • Internal links [ [#some-id] ] links to the entry with the CUSTOMID property set to 'some-id'
  • External links (schema-based)
  • Handling links

    Short-cut 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 %

TO-DO 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.

  • 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'
  • Prioritizing TODO items
    • Add a "Priority Cookie" to the headline of a TODO item.
      • TODO [#A] A permanent high-priority todo.

        Short-cut Action
        C-c , Set the priority of the current headline
        S-UP/DOWN Increase/decrease priority of current headline
  • 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 [0/0] [0%]
      • TODO This item is open
      • DONE This item is closed CLOSED: <2012-11-16 22:31:00>
  • TODO Another todo with lists of items [0/5]

    :COOKIEDATA: todo recursive

    • [ ] This is subtask ONE [0/2]
      • [ ] Item 1-1
      • [ ] Item 1-2
    • [ ] This is subtask TWO [0/0]
    • [ ] This is subtask THREE [0%]

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.
    • File level tags are inherited by all items in the file. They are set thus
      • #+FILETAGS: :TOP:LEVEL:TAGS:
  • Setting tags

    Short-cut 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
    • #+TAGS: @work(w) @home(h) @clojure(c)
  • Tag Searches Once a system of tags has been set up, it can be used to collect related information into special lists

    Short-cut 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.

Short-cut 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.

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>

Short-cut Action
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.
  • A timestamp may be preceded by a special keyword to facilitate planning
    • DEADLINE 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.
    • SCHEDULED 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.

Short-cut 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 block.

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)

Short-cut 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

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   urgent incomplete

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:     userid@exampledomain.org
#+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:

Publishing   incomplete

Working with source code   urgent incomplete

Structure of code blocks

(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 ~ ")"
}

Miscellaneous   incomplete