h1. How Scroll handles Headings
{excerpt}Scroll not only converts pages to (DocBook) sections, but also converts headings within a single page into sections. As the Confluence does not enforce proper ordering of headings (h2 can come before h1, etc.), Scroll needs interpret, what the users want. This page explains the algorithm behind this interpretation.{excerpt}
h2. 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.
{code:title=Unsorted Headings - Wiki Source}h2. Heading 1
h1. Heading 2
h2. Heading 3{code}
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:
{code:title=Unsorted Headings - TOC Structure}Heading 1
Heading 2
Heading 3{code}
h2. Initial heading on a page
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:
{code:title=Initial Headings - Wiki Source}h1. Installation Guide
h2. Prerequisites
h2. Step-by-step
h2. Trouble-Shooting{code}
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:
{code:title=Initial Headings - TOC Structure}Installation Guide
Prerequisites
Step-by-step
Trouble-Shooting{code}
Without this special handling, the table of contents would look like the following:
{code:title=Initial Headings - unwanted TOC Structure}Installation
Installation Guide
Prerequisites
Step-by-step
Trouble-Shooting{code}
{excerpt}Scroll not only converts pages to (DocBook) sections, but also converts headings within a single page into sections. As the Confluence does not enforce proper ordering of headings (h2 can come before h1, etc.), Scroll needs interpret, what the users want. This page explains the algorithm behind this interpretation.{excerpt}
h2. 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.
{code:title=Unsorted Headings - Wiki Source}h2. Heading 1
h1. Heading 2
h2. Heading 3{code}
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:
{code:title=Unsorted Headings - TOC Structure}Heading 1
Heading 2
Heading 3{code}
h2. Initial heading on a page
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:
{code:title=Initial Headings - Wiki Source}h1. Installation Guide
h2. Prerequisites
h2. Step-by-step
h2. Trouble-Shooting{code}
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:
{code:title=Initial Headings - TOC Structure}Installation Guide
Prerequisites
Step-by-step
Trouble-Shooting{code}
Without this special handling, the table of contents would look like the following:
{code:title=Initial Headings - unwanted TOC Structure}Installation
Installation Guide
Prerequisites
Step-by-step
Trouble-Shooting{code}