Previous: Sparse trees, Up: Document structure

2.8 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-mode supports editing such lists, and the HTML exporter (see Exporting) does parse and format them.

Org-mode knows ordered and unordered lists. Unordered list items start with `-', `+', or `*'1 as bullets. Ordered list items start with `1.' or `1)'. 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. For example: 

     ** Lord of the Rings
        My favorite scenes are (in this order)
        1. The attack of the Rohirrim
        2. Eowyns 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, not individual scenes matter but the film as a whole.

Org-mode supports these lists by tuning filling and wrapping commands to deal with them correctly2.

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 if you set the variable org-cycle-include-plain-lists. 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.
M-<RET>
Insert new item at current level. With prefix arg, force a new heading (see 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. 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 Checkboxes).
S-<up>
S-<down>
Jump to the previous/next item in the current list.
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-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 Checkboxes) in the item line, toggle the state of the checkbox. Otherwise, if this is an ordered list, renumber the ordered list at the cursor.

Footnotes

[1] When using `*' as a bullet, lines must be indented or they will be seen as top-level headlines. Also, when you are hiding leading stars to get a clean outline view, plain list items starting with a star are visually indistinguishable from true headlines. In short: even though `*' is supported, it may be better not to use it for plain list items

[2] Org-mode only changes the filling settings for Emacs. For XEmacs, you should use Kyle E. Jones' filladapt.el. To turn this on, put into .emacs: 

     (require 'filladapt)