The org-cycle-separator-lines variable determines hwo Org hides trailing lines when collapsing document sections.
It’s options are confusing at first glance, as it takes either a positive or negative number, but should make more sense with some examples.
Consider the following example file:
* Zero This section has no trailing blank lines. * One This section has one trailing blank line. * Two This section has two trailing blank lines. * Three This section has three trailing blank lines.
When the separator lines configuration is left on the default of two, Org requires two lines in the file to keep an empty line between collapsed headers. Collapsing the example file above yields the following restult:
* Zero... * One... * Two... * Three...
Setting the configuration value to 1 gives this result, as all sections have at least one line of whitespace:
* Zero... * One... * Two... * Three...
A special case is added for a configuration value of zero, which always hides all lines between sections:
* Zero... * One... * Two... * Three...
Finally, a negative value disables the whitespace hiding altogether:
* Zero... * One... * Two... * Three...
As a final caveat; negative options hide whitespace only if the number of blank lines is at least -N, where N is the org-cycle-separator-lines value.
Setting it to -2 collapses all whitespace smaller than two lines:
* Zero... * One... * Two... * Three...
I opt for -1 in my configuration, which disables hiding altogether, for the simple reason that it shows when a section has too much trailing whitespace.
That allows me to go in and fix the document, rather than hiding the problem.
(use-package org :custom (org-cycle-separator-lines -1))