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

### 15.8 A cleaner outline view

Some people find it noisy and distracting that the Org headlines start with a potentially large number of stars, and that text below the headlines is not indented. While this is no problem when writing a book-like document where the outline headings are really section headings, in a more list-oriented outline, indented structure is a lot cleaner:

         * 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

If you are using at least Emacs 23.21 and version 6.29 of Org, this kind of view can be achieved dynamically at display time using `org-indent-mode`. In this minor mode, all lines are prefixed for display with the necessary amount of space2. Also headlines are prefixed with additional stars, so that the amount of indentation shifts by two3 spaces per level. All headline stars but the last one are made invisible using the `org-hide` face4 - see below under ‘`2.`’ for more information on how this works. You can turn on `org-indent-mode` for all files by customizing the variable `org-startup-indented`, or you can turn it on for individual files using

         #+STARTUP: indent

If you want a similar effect in an earlier version of Emacs and/or Org, or if you want the indentation to be hard space characters so that the plain text file looks as similar as possible to the Emacs display, Org supports you in the following way:

1. Indentation of text below headlines
   You may indent text below each headline to make the left boundary line up with the headline, like

                 *** 3rd level
                     more text, now indented

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

2. Hiding leading stars
   You can modify the display in such a way that all leading stars become invisible. To do this in a global way, configure the variable `org-hide-leading-stars` or change this on a per-file basis with

                 #+STARTUP: hidestars
                 #+STARTUP: showstars

   With hidden stars, the tree becomes:

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

   The leading stars are not truly replaced by whitespace, they are only fontified with the face `org-hide` that uses the background color as font color. If you are not using either white or black background, you may have to customize this face to get the wanted effect. Another possibility is to set this font such that the extra stars are almost invisible, for example using the color `grey90` on a white background.

3. Things become cleaner still if you skip all the even levels and use only odd levels 1, 3, 5..., effectively adding two stars to go from one outline level to the next6. In this way we get the outline view shown at the beginning of this section. In order to make the structure editing and export commands handle this convention correctly, configure the variable `org-odd-levels-only`, or set this on a per-file basis with one of the following lines:

                 #+STARTUP: odd
                 #+STARTUP: oddeven

   You can convert an Org file from single-star-per-level to the double-star-per-level convention with `M-x org-convert-to-odd-levels RET` in that file. The reverse operation is `M-x org-convert-to-oddeven-levels`.

#### Footnotes

[1] Emacs 23.1 can actually crash with `org-indent-mode`

[2] `org-indent-mode` also sets the `wrap-prefix` property, such that `visual-line-mode` (or purely setting `word-wrap`) wraps long lines (including headlines) correctly indented.

[3] See the variable `org-indent-indentation-per-level`.

[4] Turning on `org-indent-mode` sets `org-hide-leading-stars` to `t` and `org-adapt-indentation` to `nil`.

[5] See also the variable `org-adapt-indentation`.

[6] When you need to specify a level for a property search or refile targets, ‘`LEVEL=2`’ will correspond to 3 stars, etc.