How Scroll handles Headings

When parsing a tree of wiki pages, Scroll converts both the page hierarchy and the headings within a page into hierarchical sections. As the Confluence does not enforce proper ordering of headings (h2 can come before h1, etc.) Scroll uses an algorithm to create a sensible hierarchy in every case. This page explains the algorithm.

Finding the Correct Hierarchy and Level

In order to create a hierarchy of sections Scroll will set the highest level of heading on a page, when it detects the first heading. All subsequent headings cannot be of higher level as this first heading, and will therefore be sorted in on a lower level as they actually are.

h2. Heading 1
h1. Heading 2
h2. Heading 3 

In this example heading 2 and Heading 1 will be on highest level. Heading 3 will be one level below. This is because, Heading 1 set the highest level, and Heading 2 cannot be higher. However, Heading 3 has a lower level as Heading 2 and comes after Heading 2 - therefore it will be on level below Heading 2. The hierarchy in the table of contents will be:

Heading 1
Heading 2
  Heading 3 

Heading Promotion

During the development and testing of Scroll, we found out that many users create a single highest-level heading on top of every page, which basically repeats the title of the wiki page. This leads to an (in most cases) unwanted additional level in the hierarchy. Scroll therefore removes this additional hierarchy level by using the first, highest-level heading on the page and omitting the page title.

For example: We have a page called "Installation", which has the structure as follows:

h1. Installation Guide
h2. Prerequisites 
h2. Step-by-step
h2. Trouble-Shooting 

In this case the page title "Installation" will be omitted, instead we use "Installation Guide" as the title of the section. That way we get a table of contents like the following:

Installation Guide
  Prerequisites
  Step-by-step
  Trouble-Shooting 

Without this special handling, the table of contents would look like the following:

Installation
  Installation Guide
    Prerequisites
    Step-by-step
    Trouble-Shooting