Document Structure
Every Org file is a tree. Headlines form the branches, and everything else (paragraphs, lists, tables, code, metadata) hangs from those branches. Once you see a file as a tree, most of Org’s commands become predictable: they show part of the tree, hide part of it, move a branch, or search inside it.
This chapter covers the parts of Org that shape and navigate that tree: headlines, visibility, motion, structure editing, sparse trees, plain lists, drawers and blocks. It closes with two display options, Org Indent mode and dynamic numbering, that change how the tree looks without changing the file.
Headlines: the backbone of a file
A headline is a line that starts at the left margin with one or more asterisks followed by a space. The number of asterisks is the headline’s level. A level 2 headline under a level 1 headline is its child; two headlines of the same level under the same parent are siblings.
* Projects
** Home server
*** Buy disks
Two 2 TB SSDs, mirrored.
*** Install the OS
** Website
* Reading list
Three terms recur throughout the book, so it helps to fix them now:
| Term | Meaning |
|---|---|
| Entry | A headline together with the text directly under it, up to the next headline of any level. |
| Section | The text of an entry without its headline line. |
| Subtree | A headline, its section, and all its descendants. |
In the example above, the subtree of ** Home server contains both level 3 headlines and the text about the SSDs. When you fold ** Home server, the whole subtree disappears behind one line; when you move it, the whole subtree moves.
The anatomy of a headline
A headline is more than a title. Between the stars and the end of the line, Org recognizes several optional components, always in a fixed order.
Figure 3.1: Each optional part of a headline has a fixed position, which is what lets Org parse it reliably.
The figure labels come from the Org parser itself. Running org-element-at-point on that headline in Org 9.8.13 reports these properties:
:level => 2
:todo-keyword => "TODO"
:todo-type => todo
:priority => 65
:commentedp => t
:raw-value => "Write chapter 3 [1/2]"
:title => "Write chapter 3 [1/2]"
:tags => ("book" "draft")
The priority is stored as a character code (65 is A), and the statistics cookie [1/2] stays inside the title. Each component has its own chapter:
- TODO keywords, priorities and statistics cookies: TODO Items.
- Tags: Tags, Properties and Column View.
- The
COMMENTkeyword marks a subtree that the exporter skips: Exporting.
Only the stars and the space are required. * Groceries is a complete, valid headline.
Reserved titles and blank lines
One headline title has a special meaning. The variable org-footnote-section (default "Footnotes") names the heading under which Org collects footnote definitions, so do not use that title for ordinary content.
Blank lines also matter. A single empty line after a subtree belongs to the subtree and is hidden when the subtree is folded. If you leave at least two empty lines, one of them stays visible in the folded view, which can make a long outline easier to scan. The threshold is controlled by org-cycle-separator-lines (default 2).
Visibility cycling
The main reason to use an outliner is that you can hide what you are not working on. Org reduces folding to two keys: TAB acts on the subtree at point, and S-TAB acts on the whole buffer. Each key rotates through three states.
stateDiagram-v2
direction LR
state "Local: TAB on a headline" as local {
FOLDED --> CHILDREN: TAB
CHILDREN --> SUBTREE: TAB
SUBTREE --> FOLDED: TAB
}
state "Global: S-TAB anywhere" as global {
OVERVIEW --> CONTENTS: S-TAB
CONTENTS --> SHOW_ALL: S-TAB
SHOW_ALL --> OVERVIEW: S-TAB
}
Figure 3.2: TAB rotates one subtree through three states, while S-TAB rotates the entire buffer through three corresponding states.
The local states mean the following:
- FOLDED shows only the headline.
- CHILDREN shows the headline’s own text and the headlines of its direct children, but not their contents.
- SUBTREE shows everything below the headline.
Two edge cases are worth knowing. If the entry has no text and no children, TAB only reports EMPTY ENTRY. If the entry has text but no children, Org skips the CHILDREN state and goes straight to SUBTREE, because org-cycle-skip-children-state-if-no-children is t by default.
The global states are OVERVIEW (top-level headlines only), CONTENTS (all headlines, no body text) and SHOW ALL. With a numeric prefix, S-TAB shows headlines down to that level: C-u 2 S-TAB displays levels 1 and 2.
Here is a small file and what each global state leaves visible. The output was produced in batch Emacs by calling org-cycle-overview and org-cycle-content and printing only the visible characters.
#+TITLE: Home server
* Hardware
A small fanless box.
** Disks
Two mirrored SSDs.
** Network
FIXME: assign a static address.
* Services
** Backup
Nightly at 02:00.
** Media
FIXME: move the library.
==== overview
#+TITLE: Home server
* Hardware
* Services
==== contents
#+TITLE: Home server
* Hardware
** Disks
** Network
* Services
** Backup
** Media
Pressing TAB three times on * Services from the overview produces the three local states. After the first press you see ** Backup and ** Media; after the second you also see their text; after the third, * Services is folded again.
More visibility commands
TAB and S-TAB cover daily work. The remaining commands help when you need a specific view.
| Key | Command | Effect |
|---|---|---|
C-u C-u TAB | org-cycle-set-startup-visibility | Return to the visibility the file had when it was opened. |
C-u C-u C-u TAB | org-fold-show-all | Reveal the whole buffer, drawers included. |
C-c C-r | org-fold-reveal | Show the context around point: the current entry, the following heading, and the headlines above. |
C-c C-k | org-kill-note-or-show-branches | Show all headings of the subtree without their bodies. |
C-c TAB | org-fold-show-children | Show the direct children; with a numeric prefix N, down to level N. |
C-c C-x b | org-tree-to-indirect-buffer | Show the current subtree in a separate indirect buffer. |
C-c C-x v | org-copy-visible | Copy only the visible text of the region. |
org-fold-reveal (also available under its older name org-reveal) is most useful after a search or an agenda jump has dropped you inside a mostly folded file. org-tree-to-indirect-buffer is a good way to focus on one project: the indirect buffer shares its text with the original, so edits appear in both places.
Inside a table, S-TAB moves to the previous field instead of cycling. If you want TAB at the very beginning of a buffer (before the first headline) to cycle globally, set org-cycle-global-at-bob to t.
Initial visibility
When Emacs opens an Org file, it shows everything by default, because org-startup-folded is showeverything. You can change the default globally or per file. A per-file setting is a #+STARTUP: line anywhere in the buffer:
#+STARTUP: overview
The values for initial visibility are overview, content, showall, show2levels to show5levels, and showeverything. The difference between showall and showeverything is drawers: showeverything also opens them.
A single subtree can override the file-wide setting through its VISIBILITY property, with one of the values folded, children, content or all:
* Archive of old notes
:PROPERTIES:
:VISIBILITY: folded
:END:
Properties are covered in Tags, Properties and Column View. C-u C-u TAB restores exactly this combination of startup option and VISIBILITY properties, so it is a quick way to tidy a buffer after a long editing session.
Protecting hidden text
Folding creates a risk: you might delete or type inside text you cannot see. Org checks for this. The variable org-fold-catch-invisible-edits (default smart) decides how cautious Org is, and org-fold-catch-invisible-edits-commands lists the commands that are checked. Setting the first variable to nil turns the protection off, which is rarely a good idea.
Moving between headlines
The motion commands treat headlines as stepping stones, skipping the body text in between.
| Key | Command | Moves to |
|---|---|---|
C-c C-n | org-next-visible-heading | The next visible headline. |
C-c C-p | org-previous-visible-heading | The previous visible headline. |
C-c C-f | org-forward-heading-same-level | The next sibling. |
C-c C-b | org-backward-heading-same-level | The previous sibling. |
C-c C-u | org-up-heading | The parent headline. |
C-c C-j | org-goto | A headline you choose in a temporary outline view. |
org-goto is the tool for long files. It opens a copy of the outline in which you can fold, unfold and search; when you press RET, point moves to the chosen headline in the original buffer, and the buffer’s visibility stays as it was. By default you can type to start an incremental search immediately (org-goto-auto-isearch is t). The variable org-goto-interface switches to a different interface that reads an outline path with completion.
If you turn on Emacs’s repeat-mode, these motion keys become repeatable. After C-c C-n, you can press n, p, f, b or u alone to keep moving, until you press any other key. The bindings live in org-navigation-repeat-map; block and link navigation (C-c M-f, C-c M-b, C-c C-x C-n, C-c C-x C-p) have their own repeat maps, org-block-navigation-repeat-map and org-link-navigation-repeat-map.
Editing the structure
Because a subtree is a unit, Org lets you insert, promote, move and copy whole subtrees with single commands. The commands are designed so that the tree stays valid after every step.
Inserting headlines
M-RET (org-meta-return) inserts a new headline at the same level as the current one. Its exact behavior depends on where point is:
- At the beginning of a headline, the new headline is created before the current line.
- At the beginning of an ordinary text line, that line becomes a headline.
- In the middle of a line, Org splits the line, and the text after point becomes the title of the new headline. Customize
org-M-RET-may-split-lineto keep lines intact.
For example, with point after groceries in * Buy groceries and cook dinner, M-RET produces two headlines, * Buy groceries and * and cook dinner (the space before and comes along with the split text).
C-RET (org-insert-heading-respect-content) is often more convenient: it always inserts the new headline after the end of the current subtree, so you never split a subtree by accident. M-S-RET and C-S-RET do the same as M-RET and C-RET but add a TODO keyword.
When the new headline is still empty, TAB changes its level: the first press makes it a child of the previous headline, further presses move it up through the parent levels, and eventually it returns to where it started. This is the fastest way to place a new headline at the right depth.
Promoting, demoting and moving
| Key | Command | Effect |
|---|---|---|
M-LEFT / M-RIGHT | org-do-promote / org-do-demote | Change the level of the current headline only. |
M-S-LEFT / M-S-RIGHT | org-promote-subtree / org-demote-subtree | Change the level of the whole subtree. |
M-UP / M-DOWN | org-move-subtree-up / org-move-subtree-down | Swap the subtree with its previous or next sibling. |
The difference between the plain and the shifted promote commands matters. M-RIGHT on a headline with children demotes only that headline, which can make its former children its siblings. M-S-RIGHT keeps the subtree intact. Here is org-demote-subtree applied to * Website:
* Projects
* Website
** Pick a theme
** Write the about page
* Reading
* Projects
** Website
*** Pick a theme
*** Write the about page
* Reading
M-UP and M-DOWN never break the hierarchy: they swap a subtree only with a sibling of the same level. With point on * Reading in the file * Projects, * Website (with a child), * Reading, one M-UP gives * Projects, * Reading, * Website, and the child ** Pick a theme travels with * Website.
If the region is active, the promote and demote commands act on every headline in it. Many other commands (scheduling, setting TODO states) also loop over all headlines in an active region; this is controlled by org-loop-over-headlines-in-active-region (default t).
Cutting, copying and pasting subtrees
| Key | Command | Effect |
|---|---|---|
C-c @ | org-mark-subtree | Mark the subtree; repeat to extend the mark to following siblings. |
C-c C-x C-w | org-cut-subtree | Kill the subtree. |
C-c C-x M-w | org-copy-subtree | Copy the subtree to the kill ring. |
C-c C-x C-y | org-paste-subtree | Yank a subtree, adjusting its level to fit the location. |
C-y | org-yank | Yank; subtrees are folded after yanking by default. |
org-paste-subtree is the careful way to paste: it changes the levels of the yanked subtree so that it fits at point. With C-u it inserts the subtree as a sibling, with C-u C-u as a child. Plain C-y runs org-yank, which by default does not adjust levels (org-yank-adjusted-subtrees is nil) but folds the pasted subtree (org-yank-folded-subtrees is t). Use C-u C-y for a completely ordinary yank.
Two related commands copy structure in bulk:
C-c C-x c(org-clone-subtree-with-time-shift) creates several sibling copies of a subtree and can shift the timestamps in each copy, for example to prepare one entry per weekly meeting.C-c C-w(org-refile) moves an entry to another place, possibly in another file. Refiling is a central part of task management and is covered in Capture, Refile, Archive and Attachments.
Sorting
C-c ^ (org-sort) sorts the children of the current headline, or all entries in the active region. It asks for a sorting key: alphabetical, numeric, by time (several kinds of timestamp), by priority, by TODO keyword, by a property value, or by a function you supply. An uppercase key reverses the order, and C-u makes alphabetical sorting case-sensitive.
Sorting * Shopping alphabetically (C-c ^ a) changes the order of its children:
* Shopping
** milk
** bread
** apples
* Shopping
** apples
** bread
** milk
Narrowing and converting
Narrowing restricts the buffer to one part, so that commands and searches cannot reach the rest. C-x n s (org-narrow-to-subtree) narrows to the current subtree, C-x n b (org-narrow-to-block) to the current block, and C-x n w (widen) shows the whole buffer again.
C-c * (org-toggle-heading) converts in both directions. On an ordinary line or a list item it creates a headline at the appropriate level; on a headline it removes the stars. With point on A plain line under * Ideas, the result is a child headline:
* Ideas
** A plain line
Sparse trees
A sparse tree is a view in which the whole file is folded except for the parts that match a query, together with the headlines above them. It answers questions such as “where did I write FIXME?” without losing the context of each match.
All sparse tree commands start from one dispatcher, C-c / (org-sparse-tree), which asks for a second key. The simplest is C-c / r (or C-c / /), org-occur, which searches for a regular expression. Applied to the home server file from earlier with the pattern FIXME, it leaves exactly this visible:
#+TITLE: Home server
* Hardware
** Network
FIXME: assign a static address.
* Services
** Media
FIXME: move the library.
Each match is also highlighted. The highlights disappear when you edit the buffer or press C-c C-c (governed by org-remove-highlights-with-change). With C-u, a new search keeps the previous highlights, so you can combine several queries. M-g n and M-g p (next-error and previous-error) jump between matches.
The regular expressions are Emacs Lisp regular expressions, so alternation is written \|: the pattern FIXME\|TODO matches either word. How much context Org reveals around a match is controlled by org-fold-show-context-detail.
The other sparse tree commands select headlines by TODO state, tags, properties or dates; they are described in TODO Items, Tags, Properties and Column View and Dates and Times. A search you run often can be given its own key in the agenda dispatcher:
(setq org-agenda-custom-commands
'(("f" occur-tree "FIXME")))
After this, C-c a f (assuming org-agenda is bound to C-c a, as in Getting Started) builds the FIXME sparse tree in the current buffer. Custom commands are covered fully in Agenda Views.
Plain lists
Headlines give a file its large-scale structure. Inside an entry, plain lists provide finer structure without creating new entries. Org recognizes three kinds:
- Unordered items start with
-,+or*(a*bullet needs indentation, otherwise it would be a headline). - Ordered items start with a number followed by
.or), such as1.or1). - Description items are unordered items that contain
::to separate a term from its description.
* Release checklist
Before tagging a release:
1. Update the changelog
2. Run the test suite
- unit tests
- integration tests, which need the staging database
3. [@5] Bump the version number
Terms used above:
- Changelog :: The file etc/NEWS in the repository.
- Staging :: The shared test environment.
Indentation defines the structure. All items of one list must start at the same indentation, and an item ends before the next line that is indented as much as its bullet or less. A list ends when every item has ended, or before two consecutive blank lines. In the example, Terms used above: is not indented, so it closes the numbered list and starts a new paragraph.
The [@5] cookie sets the counter of an ordered item: the third item is numbered 5, and any following items continue from there. When you repair this list with C-c C-c (described below), Org rewrites the bullet as 5. [@5] Bump the version number, so the plain text shows the same number as the export.
List commands
Most list commands share their keys with the headline commands, so the habits you build for headlines transfer directly.
| Key | Effect on a list item |
|---|---|
M-RET | Insert a new item at the same level (split the item if point is in the middle). |
M-S-RET | Insert a new item with a checkbox. |
TAB | Fold the item; in an empty new item, change its level. |
M-UP / M-DOWN | Move the item with its sub-items; ordered lists are renumbered. |
M-LEFT / M-RIGHT | Change the indentation of the item only. |
M-S-LEFT / M-S-RIGHT | Change the indentation of the item and its sub-items. |
C-c C-c | Toggle a checkbox, and repair bullets, indentation and numbering. |
C-c - | Cycle the bullet style of the whole list level. |
S-LEFT / S-RIGHT | Also cycle the bullet style (when shift selection is off). |
C-c * | Turn the item into a headline. |
C-c C-* | Turn the whole list into subtrees of the current headline. |
C-c ^ | Sort the list. |
Repairing a list is a frequent need after manual editing. With point on any item, C-c C-c renumbers an ordered list:
Steps:
1. Install Emacs
3. Open a file
7. Save it
Steps:
1. Install Emacs
2. Open a file
3. Save it
C-c - rotates the bullet type, for example from - to +. C-c C-* (org-list-make-subtree) is useful when a list outgrows itself and its items deserve to become entries. Checkboxes become TODO keywords on the way:
* Trip
- [ ] Book flights
- [X] Renew passport
- Pack
* Trip
** TODO Book flights
** DONE Renew passport
** Pack
Checkboxes and their statistics cookies are covered in TODO Items.
Tuning lists
A few variables adjust list behavior:
org-list-demote-modify-bulletchanges the bullet automatically when you demote an item, which helps distinguish levels visually.org-list-indent-offset(default 0) adds extra indentation to sub-items.org-list-automatic-rulescontrols the automatic corrections that list commands apply; disable individual rules if one gets in your way.org-cycle-include-plain-lists(defaultt) letsTABfold list items. The valueintegratemakes items behave like low-level headlines during cycling.org-plain-list-ordered-item-terminatorrestricts ordered items to.or).
Lists or headlines?
The two structures overlap, so a rule of thumb helps.
| Use a headline when | Use a list when |
|---|---|
| The item needs its own TODO state, tags, dates or properties. | The items are short and belong to one entry. |
| You want it to appear in the agenda. | You want a checklist inside a single task. |
| It will collect notes, logs or attachments over time. | Order and grouping are all the structure you need. |
C-c * and C-c C-* make the decision reversible, so you can start with a list and promote items later.
Drawers
Some information belongs to an entry but should normally stay out of sight: metadata, logs, private notes. A drawer holds such information. It starts with a line containing a name between colons and ends with :END::
** Weekly meeting
Agenda is in the shared folder.
:NOTES:
Ask about the budget before Friday.
:END:
After the drawer, ordinary text continues.
A drawer can contain anything except a headline or another drawer. When you cycle visibility on the headline, the drawer stays collapsed to its first line; to open it, move point to the drawer line and press TAB.
C-c C-x d (org-insert-drawer) inserts a drawer at point and asks for its name; with an active region, it wraps the region in the drawer. M-TAB completes drawer names.
Two drawer names have built-in meanings:
PROPERTIESholds the entry’s properties and must come directly after the headline (and its planning line, if any). With a prefix argument,C-c C-x dcreates it. It cannot be used for anything else. See Tags, Properties and Column View.LOGBOOKcan collect state-change notes and clock records.C-c C-zadds a time-stamped note to it. See TODO Items and Clocking, Effort and Timers.
The order of these parts inside an entry is fixed, which is why Org can find them quickly.
flowchart TD
H["Headline: ** TODO Weekly meeting :work:"] --> P["Planning line: SCHEDULED / DEADLINE"]
P --> PD["PROPERTIES drawer"]
PD --> LB["LOGBOOK and other drawers"]
LB --> B["Body: paragraphs, lists, tables, blocks"]
B --> C["Child headlines (next level)"]
Figure 3.3: An entry is read top to bottom: the planning line and the PROPERTIES drawer must directly follow the headline, while other drawers and the body can follow in any arrangement.
Blocks
A block is a region delimited by #+BEGIN_NAME and #+END_NAME lines. Blocks hold content that needs special treatment: quotations, examples, source code, export-specific snippets, or the output of dynamic computations.
#+BEGIN_QUOTE
Simple things should be simple.
#+END_QUOTE
Keywords and block names are case-insensitive, so #+begin_quote is equally valid; Org’s own insertion commands use lowercase. The kinds of block and their meanings are described in Markup for Rich Contents and, for code, in Working with Source Code.
For structure, the important point is that blocks fold like headlines. Press TAB on the #+BEGIN line to hide or show the contents. To fold all blocks when a file opens, set org-hide-block-startup or use one of these lines:
#+STARTUP: hideblocks
#+STARTUP: nohideblocks
A cleaner outline view
Long chains of stars can make a deep outline look busy, and text under a level 4 headline still starts at column 0. Org offers two ways to get an indented view.
Org Indent mode
M-x org-indent-mode changes only the display. Each headline shows a single visible star, and the text below it is shifted by virtual spaces so that it lines up with the headline text. The file on disk does not change, so collaborators and other tools see a normal Org file.
File contents With Org Indent mode
* Top level * Top level
** Second level * Second level
some text some text
*** Third level * Third level
more text more text
Each level is shifted by org-indent-indentation-per-level characters (default 2). By default, Org Indent mode also hides leading stars and locally disables org-adapt-indentation. To change this, customize org-indent-mode-turns-on-hiding-stars (for the stars) or org-indent-mode-turns-off-org-adapt-indentation (for the indentation).
To use it everywhere, set org-startup-indented to t; for a single file, add #+STARTUP: indent (or noindent to override a global setting).
Hard indentation
If the file itself should look indented, even in another editor, Org can write real spaces instead:
(setq org-adapt-indentation t
org-hide-leading-stars t
org-odd-levels-only t)
org-adapt-indentationmakes filling and structure editing indent text to match its headline. The valueheadline-datalimits this to planning lines and drawers.org-hide-leading-starspaints all stars but the last in the background color (theorg-hideface). The per-file equivalents are#+STARTUP: hidestarsandshowstars.org-odd-levels-onlyuses only levels 1, 3, 5 and so on, which doubles the visual step between levels. The per-file equivalents are#+STARTUP: oddandoddeven. To convert an existing file, useM-x org-convert-to-odd-levelsorM-x org-convert-to-oddeven-levels.
Virtual indentation is the better default: it costs nothing in the file and can be switched off at any time. Choose hard indentation only when the plain file must look indented outside Emacs.
Dynamic headline numbering
Headlines in Org carry no numbers, which keeps reordering cheap. When you want numbers on screen, for example while discussing a document in a meeting, turn on M-x org-num-mode. It displays numbers in front of the headlines and updates them as you edit the structure; the file itself is unchanged.
You can exclude headlines from numbering by level (org-num-max-level), by tag (org-num-skip-tags), when they are commented (org-num-skip-commented), when they have a non-nil UNNUMBERED property (org-num-skip-unnumbered), or when they are the footnote section (org-num-skip-footnotes). All five are off by default. In this example only org-num-skip-tags is set to ("noexport"):
* Intro
* Setup
** Install
** Configure
* Notes :noexport:
* Appendix
:PROPERTIES:
:UNNUMBERED: t
:END:
Org 9.8.13 numbers the headlines as follows (the strings are the overlays that org-num-mode adds):
* Intro "1 "
* Setup "2 "
** Install "2.1 "
** Configure "2.2 "
* Notes :noexport: (none)
* Appendix "3 "
The tagged headline is skipped, but * Appendix is still numbered, because org-num-skip-unnumbered is nil by default. Set it to t if numbering should follow the same UNNUMBERED property that export uses.
The appearance is controlled by org-num-face and org-num-format-function. To turn the mode on for every file, set org-startup-numerated to t; for one file, use #+STARTUP: num.
Summary
- A file is a tree of headlines; an entry is a headline with its text, and a subtree adds all descendants.
TABcycles a subtree andS-TABcycles the buffer, each through three states.C-c C-n,C-c C-p,C-c C-f,C-c C-b,C-c C-uandC-c C-jmove between headlines.M-RET,C-RET, theM-arrow keys andC-c ^insert, restructure and sort; prefer the subtree variants when children are involved.C-c /builds sparse trees that answer a query while keeping the context.- Plain lists, drawers and blocks add structure inside an entry.
- Org Indent mode and Org Num mode change the display only.
Further reading
- Official manual: Document Structure, Headlines, Visibility Cycling, Motion, Structure Editing, Sparse Trees, Plain Lists, Drawers, Blocks, A Cleaner Outline View, Dynamic Headline Numbering, Repeating commands, Execute commands in the active region.
- Source at release 9.8.13: lisp/org-cycle.el (visibility cycling), lisp/org-list.el (plain lists), lisp/org-num.el (numbering), lisp/org-indent.el (Org Indent mode).