Plain Lists (The Org Manual)

Next: Drawers, Previous: Sparse Trees, Up: Document Structure [Contents][Index]

### 2.6 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 every exporter (see Exporting) can parse and format 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 parenthesis10, such as ‘`1.`’ or ‘`1)`’11 If you want a list to start with a different value—e.g., 20—start the text of the item with ‘`[@20]`’12. Those constructs can be used in any item of the list in order to enforce a particular numbering.
- Description list items are unordered list items, and contain the separator ‘`::`’ to distinguish 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. 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 lines. 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 Astin :: 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, 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 point 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.

`TAB` (`org-cycle`)

  Items can be folded just like headline levels. Normally this works only if point is on a plain list item. For more details, see the variable `org-cycle-include-plain-lists`. If this variable is set to `integrate`, plain list items are 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.

`M-RET` (`org-insert-heading`)

  Insert new item at current level. With a prefix argument, force a new heading (see Structure Editing). If this command is used in the middle of an item, that item is split in two, and the second part becomes the new item13. If this command is executed before item’s body, the new item is created before the current one.

`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, but only if `org-support-shift-select` is off14. If not, you can still use paragraph jumping commands like `C-UP` and `C-DOWN` to quite similar effect.

`M-UP`
`M-DOWN`

  Move the item including subitems up/down15, i.e., 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 by moving point.

  As a special case, using this command on the very first item of a list moves 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.

`C-c C-c`

  If there is a checkbox (see Checkboxes) in the item line, toggle the state of the checkbox. In any case, verify bullets and indentation consistency in the whole list.

`C-c -`

  Cycle the entire list level through the different itemize/enumerate bullets (‘`-`’, ‘`+`’, ‘`*`’, ‘`1.`’, ‘`1)`’) or a subset of them, depending on `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 is changed into an item. With a prefix argument, all lines are converted to list items. If the first line already was a list item, any item marker is removed from the list. Finally, even without an active region, a normal line is 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 Structure Editing, for a detailed explanation.

`C-c C-*`

  Turn the whole plain list into a subtree of the current heading. Checkboxes (see Checkboxes) become ‘`TODO`’, respectively ‘`DONE`’, keywords when unchecked, respectively checked.

`S-LEFT`
`S-RIGHT`

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

`C-c ^`

  Sort the plain list. Prompt for the sorting method: numerically, alphabetically, by time, or by custom function.

#### Footnotes

### (9)

When using ‘`*`’ as a bullet, lines must be indented so that they are not interpreted as 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.

### (10)

You can filter out any of them by configuring `org-plain-list-ordered-item-terminator`.

### (11)

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 automatically become numbers.

### (12)

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]`’.

### (13)

If you do not want the item to be split, customize the variable `org-M-RET-may-split-line`.

### (14)

If you want to cycle around items that way, you may customize `org-list-use-circular-motion`.

### (15)

See `org-list-use-circular-motion` for a cyclic behavior.

Next: Drawers, Previous: Sparse Trees, Up: Document Structure [Contents][Index]