This is the official manual for the latest Org-mode release.

Table of Contents

Next: , Previous: The very busy C-c C-c key, Up: Miscellaneous

15.8 A cleaner outline view

Org's default outline with stars and no indents can become too cluttered for short documents. For book-like long documents, the effect is not as noticeable. Org provides an alternate stars and indentation scheme, as shown on the right in the following table. It uses only one star and indents text to line with the heading: 

     * Top level headline             |    * Top level headline
     ** Second level                  |      * Second level
     *** 3rd level                    |        * 3rd level
     some text                        |          some text
     *** 3rd level                    |        * 3rd level
     more text                        |          more text
     * Another top level headline     |    * Another top level headline

To turn this mode on, use the minor mode, org-indent-mode. Text lines that are not headlines are prefixed with spaces to vertically align with the headline text1.

To make more horizontal space, the headlines are shifted by two stars. This can be configured by the org-indent-indentation-per-level variable. Only one star on each headline is visible, the rest are masked with the same font color as the background. This font face can be configured with the org-hide variable.

Note that turning on org-indent-mode sets org-hide-leading-stars to t and org-adapt-indentation to nil; ‘2.’ below shows how this works.

To globally turn on org-indent-mode for all files, customize the variable org-startup-indented.

To turn on indenting for individual files, use #+STARTUP option as follows: 

     #+STARTUP: indent

Indent on startup makes Org use hard spaces to align text with headings as shown in examples below.

  1. Indentation of text below headlines
    Indent text to align with the headline. 
              *** 3rd level
              more text, now indented

    Org adapts indentations with paragraph filling, line wrapping, and structure editing2.

  2. Hiding leading stars
    Org can make leading stars invisible. For global preference, configure the variable org-hide-leading-stars. For per-file preference, use these file #+STARTUP options: 
              #+STARTUP: hidestars
          #+STARTUP: showstars

    With stars hidden, the tree is shown as: 

              * Top level headline
           * Second level
            * 3rd level
            ...

    Because Org makes the font color same as the background color to hide to stars, sometimes org-hide face may need tweaking to get the effect right. For some black and white combinations, grey90 on a white background might mask the stars better.

  3. Using stars for only odd levels, 1, 3, 5, ..., can also clean up the clutter. This removes two stars from each level3. For Org to properly handle this cleaner structure during edits and exports, configure the variable org-odd-levels-only. To set this per-file, use either one of the following lines: 
              #+STARTUP: odd
          #+STARTUP: oddeven

    To switch between single and double stars layouts, use M-x org-convert-to-odd-levels RET and M-x org-convert-to-oddeven-levels.

Footnotes

[1] The org-indent-mode also sets the wrap-prefix correctly for indenting and wrapping long lines of headlines or text. This minor mode handles visual-line-mode and directly applied settings through word-wrap.

[2] Also see the variable org-adapt-indentation.

[3] Because ‘LEVEL=2’ has 3 stars, ‘LEVEL=3’ has 4 stars, and so on