org: Clean view
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.2(1) 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 space(2). Also headlines are
prefixed with additional stars, so that the amount of indentation shifts
by two(3) spaces per level. All headline stars but the last one are
made invisible using the ‘org-hide’ face(4); 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 editing(5), 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 next(6). 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.
Info Catalog
org: The very busy C-c C-c key
org: Miscellaneous
org: TTY keys