How Heading Levels are Handled

When parsing a tree of wiki pages, Scroll Word Exporter converts both the page hierarchy and the headings within a page into hierarchical sections.

As Confluence does not enforce proper ordering of headings (heading 2 can come before heading 1, etc.), the exporter 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, the Scroll Exporters 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.

For example:

h2. Heading a


h1. Heading b


h2. Heading c

In this example Heading b (heading level 2 style) and Heading a (heading level 1 style) will be on highest level. Heading c (Heading level 2 style) will be one level below. This is because, Heading a set the highest level, and Heading b cannot be higher. However, Heading c has a lower level as a heading level 2 style and comes after Heading b - therefore it will be on level below Heading b.

The hierarchy in the table of contents for the generated export will be:

- h1. Heading a
- h1. Heading b
-- h2. Heading c

Heading handling for missing heading levels

In some cases it may be that a page is formatted with heading levels being omitted from the consecutive heading level sequence.

For example:

h1. Heading a


h3. Heading b


h6. Heading c

In this example Heading a (heading level 1 style) will be preserved as a heading level 1 in the generated export. However Heading b (heading level 3 style) will be elevated to a heading level 2 style in the export. Furthermore, Heading c (Heading level 6 style) will be one level below and exported as a Heading level 3 style in the export. This is because our Scroll Exporter apps close the gap between the missing heading levels on the page when generating the export to create a sensible hierarchy in the Table of Contents. 

The hierarchy in the table of contents for the generated export will be:

- h1. Heading a
- - h2. Heading b
- - - h3. Heading c

Heading Promotion

During the development and testing of the Scroll Exporters, 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 Exporters therefore remove 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:

Page title. Installation


h1. Installation Guide


h2. Prerequisites


h2. Step-by-step


h2. Troubleshooting

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 in the generated export:

- h1. Installation Guide
- - h2. Prerequisites
- - h2. Step-by-step
- - h2. Troubleshooting

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

- h1. Installation
- h1. Installation Guide
- - h2. Prerequisites
- - h2. Step-by-step
- - h2. Troubleshooting