14.5 A cleaner outline view

Some people find it noisy and distracting that the Org headlines are starting with a potentially large number of stars, and that text below the headlines is not indented. This is not really a problem when you are writing a book where the outline headings are really section headlines. However, in a more list-oriented outline, it is clear that an indented structure is a lot cleaner, as can be seen by comparing the two columns in the following example:

     * 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

It is non-trivial to make such a look work in Emacs, but Org contains three separate features that, combined, achieve just that.

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
        

   A good way to get this indentation is by hand, and Org supports this with paragraph filling, line wrapping, and structure editing¹ preserving or adapting the indentation appropriate. A different approach would be to have a way to automatically indent lines according to outline structure by adding overlays or text properties. But I have not yet found a robust and efficient way to do this in large files.

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: showstars
             #+STARTUP: hidestars
        

   With hidden stars, the tree becomes:

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

   Note that 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 next. 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.