Next: , Previous: , Up: Miscellaneous   [Contents][Index]


15.9 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
*** Third level                  |        * Third level
    some text                    |          some text
*** Third level                  |        * Third 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 text149.

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.

Note that turning on org-indent-mode sets org-hide-leading-stars to t and org-adapt-indentation to nil.

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’ keyword as follows:

#+STARTUP: indent

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

Indentation of text below headlines

Indent text to align with the headline.

*** Third level
    more text, now indented

Org supports this with paragraph filling, line wrapping, and structure editing, preserving or adapting the indentation as appropriate150.

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
  * Third level
  ...

Because Org makes the font color the 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.

Odd levels

Using stars for only odd levels, 1, 3, 5, …, can also clean up the clutter. This removes two stars from each level151. 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 and M-x org-convert-to-oddeven-levels.


Footnotes

(149)

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.

(150)

Also see the variable org-adapt-indentation.

(151)

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


Next: , Previous: , Up: Miscellaneous   [Contents][Index]