This is the official manual for the latest Org-mode release.
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 every exporter (see Exporting) can parse and format them.
Org knows ordered lists, unordered lists, and description lists.
[@20]
4. Those constructs can
be used in any item of the list in order to enforce a particular numbering.
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. An item ends before the next line that is less or equally indented than its bullet/number.
A list ends whenever every item has ended, which means before any line less or equally indented than items at top level. It also ends before two blank lines5. In that case, all items are closed. 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 correctly6, and by exporting them
properly (see Exporting). Since indentation is what governs the
structure of these lists, many structural constructs like #+BEGIN_...
blocks can be indented to signal that they belong to a particular 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
. To get a greater difference of
indentation between items and theirs sub-items, customize
org-list-indent-offset
.
The following commands act on items when the cursor is in the first line of
an item (the line with the bullet or number). Some of them imply the
application of automatic rules to keep list structure intact. If some of
these actions get in your way, configure org-list-automatic-rules
to disable them individually.
org-cycle
)org-cycle-include-plain-lists
. If this variable is set to
integrate
, plain list items will be treated like low-level
headlines. 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. In a new item with no text yet, the
first <TAB> demotes the item to become a child of the previous
one. Subsequent <TAB>s move the item to meaningful levels in the list
and eventually get it back to its initial position.
org-insert-heading
)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.
As a special case, using this command on the very first item of a list will
move the whole list. This behavior can be disabled by configuring
org-list-automatic-rules
. The global indentation of a list has no
influence on the text after the list.
org-plain-list-ordered-item-terminator
, the type of list,
and its indentation. With a numeric prefix argument N, select the Nth bullet
from this list. If there is an active region when calling this, selected
text will be changed into an item. With a prefix argument, all lines will be
converted to list items. If the first line already was a list item, any item
marker will be removed from the list. Finally, even without an active
region, a normal line will be converted into a list item.
org-support-shift-select
.
[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 may be hard to distinguish from true headlines. In short: even though ‘*’ is supported, it may be better to not use it for plain list items.
[2] You can filter out any of them by configuring
org-plain-list-ordered-item-terminator
.
[3] You can also get ‘a.’, ‘A.’, ‘a)’ and
‘A)’ by configuring org-list-allow-alphabetical
. To minimize
confusion with normal text, those are limited to one character only. Beyond
that limit, bullets will automatically fallback to numbers.
[4] If there's a checkbox in the item, the cookie
must be put before the checkbox. If you have activated alphabetical
lists, you can also use counters like [@b]
.
[5] See also org-list-empty-line-terminates-plain-lists
.
[6] Org 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)
[7] If you do not want the item to be split, customize the
variable org-M-RET-may-split-line
.
[8] If you want to
cycle around items that way, you may customize
org-list-use-circular-motion
.
[9] See
org-list-use-circular-motion
for a cyclic behavior.