Org-mode Quick Guide

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.

Motion

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:

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

Hyperlinks

Format

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

Internal links

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

External links (schema-based)

• 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

Handling links

TODO Items

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.

Further reading

• Charles Cave’s GTD setup
• Chapter 5 of the manual

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

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

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.

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>

Time planning

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

Clocking work time

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

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 “-cc” ‘org-capture)

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

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

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)

Read more about passing vars to code-blocks here