2. Document structure

Org is based on Outline mode and provides flexible commands to edit the structure of the document.

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). 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. 15.7 A cleaner outline view, describes a setup to realize this.

An empty line after the end of a subtree is considered part of it and will be hidden when the subtree is folded. However, if you leave at least two empty lines, one empty line will remain visible after folding the subtree, in order to structure the collapsed view. See the variable org-cycle-separator-lines to modify this behavior.

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

The cursor must be on a headline for this to work(2). When the cursor is at the beginning of the buffer and the first line is not a headline, then TAB actually runs global cycling (see below)(3). Also when called with a prefix argument (C-u TAB), global cycling is invoked.

S-TAB

C-u TAB

Global cycling: Rotate the entire buffer among the states

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

When S-TAB is called with a numeric prefix argument N, the CONTENTS view up to headlines of level N will be shown. Note that inside tables, S-TAB jumps to the previous field.

C-u C-u C-u TAB

Show all, including drawers.

C-c C-r

Reveal context around point, showing the current entry, the following heading and the hierarchy above. Useful for working near a location that has been exposed by a sparse tree command (see section 2.6 Sparse trees) or an agenda command (see section 10.5 Commands in the agenda buffer). With a prefix argument show, on each level, all sibling headings. With double prefix arg, also show the entire subtree of the parent.

C-c C-k

Expose all the headings of the subtree, CONTENT view for just one subtree.

C-c C-x b

Show the current subtree in an indirect buffer(4). With a numeric prefix argument N, go up to level N and then take that tree. If N is negative then go up that many levels. With a C-u prefix, do not remove the previously used indirect buffer.

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 one of the following lines anywhere in the buffer:

#+STARTUP: overview
#+STARTUP: content
#+STARTUP: showall
#+STARTUP: showeverything

Furthermore, any entries with a `VISIBILITY' property (see section 7. Properties and columns) will get their visibility adapted accordingly. Allowed values for this property are folded, children, content, and all.

C-u C-u TAB

Switch back to the startup visibility of the buffer, i.e. whatever is requested by startup options and `VISIBILITY' properties in individual entries.

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

C-c C-j

Jump to a different place without changing the current outline visibility. Shows the document structure in a temporary buffer, where you can use the following keys to find your destination:

TAB Cycle visibility. down / up Next/previous visible headline. RET Select this location. / Do a Sparse-tree search The following keys work if you turn off org-goto-auto-isearch n / p Next/previous visible headline. f / b Next/previous headline same level. u One level up. 0-9 Digit argument. q Quit

See also the variable org-goto-interface.

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 section 2.7 Plain lists). To force creation of a new headline, use a prefix argument, or first press RET to get to the beginning of the next line. 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(5). If the command is used at the beginning of a headline, the new headline is created before the current line. If at the beginning of any other line, the content of that line is made the new heading. If the command is used at the end of a folded subtree (i.e. behind the ellipses at the end of a headline), then a headline like the current one will be inserted after the end of the subtree.

C-RET

Just like M-RET, except when adding a new heading below the current heading, the new heading is placed after the body instead of before it. This command works from anywhere in the entry.

M-S-RET

Insert new TODO entry with same level as current heading. See also the variable org-treat-insert-todo-heading-as-state-change.

C-S-RET

Insert new TODO entry with same level as current heading. Like C-RET, the new headline will be inserted after the current subtree.

TAB in new, empty entry

In a new entry with no text yet, the first TAB demotes the entry to become a child of the previous one. The next TAB makes it a parent, and so on, all the way to top level. Yet another TAB, and you are back to the initial level.

M-left

Promote current heading by one level.

M-right

Demote current heading by one level.

M-S-left

Promote the current subtree by one level.

M-S-right

Demote the current subtree by one level.

M-S-up

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

M-S-down

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

C-c C-x C-w

Kill subtree, i.e. remove it from buffer but save in kill ring. With a numeric prefix argument N, kill N sequential subtrees.

C-c C-x M-w

Copy subtree to kill ring. With a numeric prefix argument N, copy the N sequential subtrees.

C-c C-x C-y

Yank subtree from kill ring. This does modify the level of the subtree to make sure the tree fits in nicely at the yank position. The yank level can also be specified with a numeric prefix argument, or by yanking after a headline marker like `****'.

C-y

Depending on the variables org-yank-adjusted-subtrees and org-yank-folded-subtrees, Org's internal yank command will paste subtrees folded and in a clever way, using the same command as C-c C-x C-y. With the default settings, no level adjustment will take place, but the yanked tree will be folded unless doing so would swallow text previously visible. Any prefix argument to this command will force a normal yank to be executed, with the prefix passed along. A good way to force a normal yank is C-u C-y. If you use yank-pop after a yank, it will yank previous kill items plainly, without adjustment and folding.

C-c C-x c

Clone a subtree by making a number of sibling copies of it. You will be prompted for the number of copies to make, and you can also specify if any timestamps in the entry should be shifted. This can be useful, for example, to create a number of tasks related to a series of lectures to prepare. For more details, see the docstring of the command org-clone-subtree-with-time-shift.

C-c C-w

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

C-c ^

Sort same-level entries. When there is an active region, all entries in the region will be sorted. Otherwise the children of the current headline are sorted. The command prompts for the sorting method, which can be alphabetically, numerically, by time (first timestamp with active preferred, creation time, scheduled time, deadline time), by priority, by TODO keyword (in the sequence the keywords have been defined in the setup) or by the value of a property. Reverse sorting is possible as well. You can also supply your own function to extract the sorting key. With a C-u prefix, sorting will be case-sensitive. With two C-u C-u prefixes, duplicate entries will also be removed.

C-x n s

Narrow buffer to current subtree.

C-x n w

Widen buffer to remove narrowing.

C-c *

Turn a normal line or plain list item into a headline (so that it becomes a subheading at its location). Also turn a headline into a normal line by removing the stars. If there is an active region, turn all lines in the region into headlines. If the first line in the region was an item, turn only the item lines into headlines. Finally, if the first line is a headline, remove the stars from all headlines in the region.

When there is an active region (Transient Mark mode), promotion and demotion work on all headlines in the region. To select a region of headlines, it is best to place both point and mark at the beginning of a line, mark at the beginning of the first headline, and point at the line just after the last headline to change. Note that when the cursor is inside a table (see section 3. Tables), the Meta-Cursor keys have different functionality.

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(6). 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. If the match is in a headline, the headline is made visible. If the match is in the body of an entry, headline and body are made visible. In order to provide minimal context, also the full hierarchy of headlines above the match is shown, as well as the headline following the match. Each match is also highlighted; the highlights disappear when the buffer is changed by an editing command(7), or by pressing C-c C-c. When called with a C-u prefix argument, previous highlights are kept, so several calls to this command can be stacked.

For frequently used sparse trees of specific search strings, you can use the variable org-agenda-custom-commands to define fast keyboard access to specific sparse trees. These commands will then be accessible through the agenda dispatcher (see section 10.2 The agenda dispatcher). For example:

(setq org-agenda-custom-commands
      '(("f" occur-tree "FIXME")))

will define the key C-c a f as a shortcut for creating a sparse tree matching the string `FIXME'.

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

To print a sparse tree, you can use the Emacs command ps-print-buffer-with-faces which does not print invisible parts of the document (8). Or you can use the command C-c C-e v to export only the visible part of the document and print the resulting file.

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 section 5.6 Checkboxes). Org supports editing such lists, and the HTML exporter (see section 12. Exporting) parses and formats them.

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

• Unordered list items start with `-', `+', or `*'(9) as bullets.
• Ordered list items start with a numeral followed by either a period or a right parenthesis, such as `1.' or `1)'. If you want a list to start a different value (e.g. 20), start the text of the item with [@start:20].
• Description list items are unordered list items, and contain the separator ` :: ' to separate the description term from the description.

Items belonging to the same list must have the same indentation on the first line. In particular, if an ordered list reaches number `10.', then the 2--digit numbers must be written left-aligned with the other numbers in the list. Indentation also determines the end of a list item. It ends before the next line that is indented like the bullet/number, or less. Empty lines are part of the previous item, so you can have several paragraphs in one item. If you would like an empty line to terminate all currently open plain lists, configure the variable org-empty-line-terminates-plain-lists. Here is an example:

** Lord of the Rings
   My favorite scenes are (in this order)
   1. The attack of the Rohirrim
   2. Eowyn's fight with the witch king
      + this was already my favorite scene in the book
      + I really like Miranda Otto.
   3. Peter Jackson being shot by Legolas
       - on DVD only
      He makes a really funny face when it happens.
   But in the end, no individual scenes matter but the film as a whole.
   Important actors in this film are:
   - Elijah Wood :: He plays Frodo
   - Sean Austin :: He plays Sam, Frodo's friend.  I still remember
     him very well from his role as Mikey Walsh in The Goonies.

Org supports these lists by tuning filling and wrapping commands to deal with them correctly(10), and by exporting them properly (see section 12. Exporting). Since indentation is what governs the structure of these lists, many structural constructs like #+BEGIN_... blocks can be indented to signal that they should be part of a list item.

If you find that using a different bullet for a sub-list (than that used for the current list-level) improves readability, customize the variable org-list-demote-modify-bullet.

The following commands act on items when the cursor is in the first line of an item (the line with the bullet or number).

TAB

Items can be folded just like headline levels. Normally this works only if the cursor is on a plain list item. For more details, see the variable org-cycle-include-plain-lists. to integrate, plain list items will be treated like low-level. The level of an item is then given by the indentation of the bullet/number. Items are always subordinate to real headlines, however; the hierarchies remain completely separated.

If org-cycle-include-plain-lists has not been set, TAB fixes the indentation of the current line in a heuristic way.

M-RET

Insert new item at current level. With a prefix argument, force a new heading (see section 2.5 Structure editing). If this command is used in the middle of a line, the line is split and the rest of the line becomes the new item(11). If this command is executed in the whitespace before a bullet or number, the new item is created before the current item. If the command is executed in the white space before the text that is part of an item but does not contain the bullet, a bullet is added to the current line.

M-S-RET

Insert a new item with a checkbox (see section 5.6 Checkboxes).

TAB in new, empty item

In a new item with no text yet, the first TAB demotes the item to become a child of the previous one. The next TAB makes it a parent, and so on, all the way to the left margin. Yet another TAB, and you are back to the initial level.

S-up

S-down

Jump to the previous/next item in the current list, but only if org-support-shift-select is off. If not, you can still use paragraph jumping commands like C-up and C-down to quite similar effect.

M-S-up

M-S-down

Move the item including subitems up/down (swap with previous/next item of same indentation). If the list is ordered, renumbering is automatic.

M-left

M-right

Decrease/increase the indentation of an item, leaving children alone.

M-S-left

M-S-right

Decrease/increase the indentation of the item, including subitems. Initially, the item tree is selected based on current indentation. When these commands are executed several times in direct succession, the initially selected region is used, even if the new indentation would imply a different hierarchy. To use the new hierarchy, break the command chain with a cursor motion or so.

C-c C-c

If there is a checkbox (see section 5.6 Checkboxes) in the item line, toggle the state of the checkbox. If not, this command makes sure that all the items on this list level use the same bullet. Furthermore, if this is an ordered list, make sure the numbering is OK.

C-c -

Cycle the entire list level through the different itemize/enumerate bullets (`-', `+', `*', `1.', `1)'). With a numeric prefix argument N, select the Nth bullet from this list. If there is an active region when calling this, all lines will be converted to list items. If the first line already was a list item, any item markers will be removed from the list. Finally, even without an active region, a normal line will be converted into a list item.

C-c *

Turn a plain list item into a headline (so that it becomes a subheading at its location). See section 2.5 Structure editing, for a detailed explanation.

S-left/right

This command also cycles bullet styles when the cursor in on the bullet or anywhere in an item line, details depending on org-support-shift-select.

C-c ^

Sort the plain list. You will be prompted for the sorting method: numerically, alphabetically, by time, or by custom function.

2.8 Drawers

Sometimes you want to keep information associated with an entry, but you normally don't want to see it. For this, Org-mode has drawers. Drawers need to be configured with the variable org-drawers(12). Drawers look like this:

** This is a headline
   Still outside the drawer
   :DRAWERNAME:
      This is inside the drawer.
   :END:
   After the drawer.

Visibility cycling (see section 2.3 Visibility cycling) on the headline will hide and show the entry, but keep the drawer collapsed to a single line. In order to look inside the drawer, you need to move the cursor to the drawer line and press TAB there. Org-mode uses the PROPERTIES drawer for storing properties (see section 7. Properties and columns), and you can also arrange for state change notes (see section 5.3.2 Tracking TODO state changes) and clock times (see section 8.4 Clocking work time) to be stored in a drawer LOGBOOK. If you want to store a quick note in the LOGBOOK drawer, in a similar way as this is done by state changes, use

C-c C-z

Add a time-stamped note to the LOGBOOK drawer.

2.9 Blocks

Org-mode uses begin...end blocks for various purposes from including source code examples (see section 11.3 Literal examples) to capturing time logging information (see section 8.4 Clocking work time). These blocks can be folded and unfolded by pressing TAB in the begin line. You can also get all blocks folded at startup by configuring the variable org-hide-block-startup or on a per-file basis by using

#+STARTUP: hideblocks
#+STARTUP: nohideblocks

2.10 Footnotes

Org-mode supports the creation of footnotes. In contrast to the `footnote.el' package, Org-mode's footnotes are designed for work on a larger document, not only for one-off documents like emails. The basic syntax is similar to the one used by `footnote.el', i.e. a footnote is defined in a paragraph that is started by a footnote marker in square brackets in column 0, no indentation allowed. If you need a paragraph break inside a footnote, use the LaTeX idiom `\par'. The footnote reference is simply the marker in square brackets, inside text. For example:

The Org homepage[fn:1] now looks a lot better than it used to.
...
[fn:1] The link is: http://orgmode.org

Org-mode extends the number-based syntax to named footnotes and optional inline definition. Using plain numbers as markers (as `footnote.el' does) is supported for backward compatibility, but not encouraged because of possible conflicts with LaTeX snippets (see section 11.7 Embedded LaTeX). Here are the valid references:

[1]

A plain numeric footnote marker. Compatible with `footnote.el', but not recommended because something like `[1]' could easily be part of a code snippet.

[fn:name]

A named footnote reference, where name is a unique label word, or, for simplicity of automatic creation, a number.

[fn:: This is the inline definition of this footnote]

A LaTeX-like anonymous footnote where the definition is given directly at the reference point.

[fn:name: a definition]

An inline definition of a footnote, which also specifies a name for the note. Since Org allows multiple references to the same note, you can then use [fn:name] to create additional references.

Footnote labels can be created automatically, or you can create names yourself. This is handled by the variable org-footnote-auto-label and its corresponding #+STARTUP keywords, see the docstring of that variable for details.

The following command handles footnotes:

C-c C-x f

The footnote action command.

When the cursor is on a footnote reference, jump to the definition. When it is at a definition, jump to the (first) reference.

Otherwise, create a new footnote. Depending on the variable org-footnote-define-inline(13), the definition will be placed right into the text as part of the reference, or separately into the location determined by the variable org-footnote-section.

When this command is called with a prefix argument, a menu of additional options is offered:

s Sort the footnote definitions by reference sequence. During editing, Org makes no effort to sort footnote definitions into a particular sequence. If you want them sorted, use this command, which will also move entries according to org-footnote-section. Automatic sorting after each insertion/deletion can be configured using the variable org-footnote-auto-adjust. r Renumber the simple fn:N footnotes. Automatic renumbering after each insertion/deletion can be configured using the variable org-footnote-auto-adjust. S Short for first r, then s action. n Normalize the footnotes by collecting all definitions (including inline definitions) into a special section, and then numbering them in sequence. The references will then also be numbers. This is meant to be the final step before finishing a document (e.g. sending off an email). The exporters do this automatically, and so could something like message-send-hook. d Delete the footnote at point, and all definitions of and references to it.

Depending on the variable org-footnote-auto-adjust(14), renumbering and sorting footnotes can be automatic after each insertion or deletion.

C-c C-c

If the cursor is on a footnote reference, jump to the definition. If it is a the definition, jump back to the reference. When called at a footnote location with a prefix argument, offer the same menu as C-c C-x f.

C-c C-o or mouse-1/2

Footnote labels are also links to the corresponding definition/reference, and you can use the usual commands to follow these links.

2.11 The Orgstruct minor mode

If you like the intuitive way the Org-mode structure editing and list formatting works, you might want to use these commands in other modes like Text mode or Mail mode as well. The minor mode orgstruct-mode makes this possible. Toggle the mode with M-x orgstruct-mode, or turn it on by default, for example in Mail mode, with one of:

(add-hook 'mail-mode-hook 'turn-on-orgstruct)
(add-hook 'mail-mode-hook 'turn-on-orgstruct++)

When this mode is active and the cursor is on a line that looks to Org like a headline or the first line of a list item, most structure editing commands will work, even if the same keys normally have different functionality in the major mode you are using. If the cursor is not in one of those special lines, Orgstruct mode lurks silently in the shadow. When you use orgstruct++-mode, Org will also export indentation and autofill settings into that mode, and detect item context after the first line of an item.

mail: