Org Mode Compact Guide Part 1: Introduction

1.1 Preface

Org is a mode for keeping notes, maintaining TODO lists, and doing project planning with a fast and effective plain-text system. It is also an authoring and publishing system.

This document is a much compressed derivative of the comprehensive Org-mode manual. It contains all basic features and commands, along with important hints for customization. It is intended for beginners who would shy back from a 200 page manual because of sheer size.

1.2 Installation

Important: If you are using a version of Org that is part of the Emacs distribution or an XEmacs package, please skip this section and go directly to Activation.

If you have downloaded Org from the Web, either as a distribution .zip or .tar file, or as a Git archive, it is best to run it directly from the distribution directory. You need to add the lisp subdirectories to the Emacs load path. To do this, add the following line to .emacs:

(setq load-path (cons "~/path/to/orgdir/lisp" load-path))

(setq load-path (cons "~/path/to/orgdir/contrib/lisp" load-path))

For speed you should byte-compile the Lisp files with the shell command:

make

Then add the following line to .emacs. It is needed so that Emacs can autoload functions that are located in files not immediately loaded when Org-mode starts.

(require 'org-install)

1.3 Activation

Add the following lines to your .emacs file. The last three lines define global keys for some commands — please choose suitable keys yourself.

;; The following lines are always needed. Choose your own keys.

(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))

(add-hook 'org-mode-hook 'turn-on-font-lock) ; not needed when global-font-lock-mode is on

(global-set-key "\C-cl" 'org-store-link)

(global-set-key "\C-ca" 'org-agenda)

(global-set-key "\C-cb" 'org-iswitchb)

With this setup, all files with extension ‘.org’ will be put into Org mode.

1.4 Feedback

If you find problems with Org, or if you have questions, remarks, or ideas about it, please mail to the Org mailing list emacs-orgmode@gnu.org. For information on how to submit bug reports, see the main manual.

2 Document Structure

2.1 Outlines

Org is implemented on top of Outline mode. Outlines allow a document to be organized in a hierarchical structure, which (at least for me) is the best representation of notes and thoughts. An overview of this structure is achieved by folding (hiding) large parts of the document to show only the general document structure and the parts currently being worked on. Org greatly simplifies the use of outlines by compressing the entire show/hide functionality into a single command, org-cycle, which is bound to the <TAB> key.

2.2 Headlines

Headlines define the structure of an outline tree. The headlines in Org start with one or more stars, on the left margin[1, See the variable org-special-ctrl-a/e to configure special behavior of C-a and C-e in headlines.]. For example:

* Top level headline

** Second level

*** 3rd level

some text

*** 3rd level

more text

* Another top level headline

Some people find the many stars too noisy and would prefer an outline that has whitespace followed by a single star as headline starters. Clean view, describes a setup to realize this.

2.3 Visibility cycling

Outlines make it possible to hide parts of the text in the buffer. Org uses just two commands, bound to <TAB> and S-<TAB> to change the visibility in the buffer.

<TAB>

Subtree cycling: Rotate current subtree among the states

,-> FOLDED -> CHILDREN -> SUBTREE --.

'-----------------------------------'

When called with a prefix argument (C-u <TAB>) or with the shift key, global cycling is invoked.

S-<TAB> and C-u <TAB>

Global cycling: Rotate the entire buffer among the states

,-> OVERVIEW -> CONTENTS -> SHOW ALL --.

'--------------------------------------'

C-u C-u C-u <TAB>

Show all, including drawers.

When Emacs first visits an Org file, the global state is set to OVERVIEW, i.e. only the top level headlines are visible. This can be configured through the variable org-startup-folded, or on a per-file basis by adding a startup keyword overview, content, showall, like this:

#+STARTUP: content

2.4 Motion

The following commands jump to other headlines in the buffer.

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.

2.5 Structure editing

M-<RET>

Insert new heading with same level as current. If the cursor is in a plain list item, a new item is created (see Plain lists). When this command is used in the middle of a line, the line is split and the rest of the line becomes the new headline[1, If you do not want the line to be split, customize the variable org-M-RET-may-split-line.].

M-S-<RET>

Insert new TODO entry with same level as current heading.

<TAB> in new, empty entry

In a new entry with no text yet, <TAB> will cycle through reasonable levels.

M-<left>/<right>

Promote/demote current heading by one level.

M-S-<left>/<right>

Promote/demote the current subtree by one level.

M-S-<up>/<down>

Move subtree up/down (swap with previous/next subtree of same level).

C-c C-w

Refile entry or region to a different location. See Refiling notes.

C-x n s/w

Narrow buffer to current subtree / widen it again

When there is an active region (Transient Mark mode), promotion and demotion work on all headlines in the region.

2.6 Sparse trees

An important feature of Org mode is the ability to construct sparse trees for selected information in an outline tree, so that the entire document is folded as much as possible, but the selected information is made visible along with the headline structure above it[1,See also the variables org-show-hierarchy-above, org-show-following-heading, org-show-siblings, and org-show-entry-below for detailed control on how much context is shown around each match.]. Just try it out and you will see immediately how it works.

Org mode contains several commands creating such trees, all these commands can be accessed through a dispatcher:

C-c /

This prompts for an extra key to select a sparse-tree creating command.

C-c / r

Occur. Prompts for a regexp and shows a sparse tree with all matches. Each match is also highlighted; the highlights disappear by pressing C-c C-c.

The other sparse tree commands select headings based on TODO keywords, tags, or properties and will be discussed later in this manual.

2.7 Plain lists

Within an entry of the outline tree, hand-formatted lists can provide additional structure. They also provide a way to create lists of checkboxes (see Checkboxes). Org supports editing such lists, and the HTML exporter (see Exporting) parses and formats them.

Org knows ordered lists, unordered lists, and description lists.

* Unordered list items start with ‘-’, ‘+’, or ‘*’ as bullets.

* Ordered list items start with ‘1.’ or ‘1)’.

* Description list use ‘ :: ’ to separate the term from the description.

Items belonging to the same list must have the same indentation on the first line. A list ends before the next line that is indented like the bullet/number, or less. An example:

** Lord of the Rings

My favorite scenes are (in this order)

1. The attack of the Rohirrim