Compare working with sections in Confluence with and without the projectdoc Toolbox.
Doctype
test-case
hide
Name
Working with Sections
Parent
Parent Property
property
Parent
property-name
Name
Audience
Name List
doctype
role
property
Audience
Subject
Name List
doctype
subject
property
Subject
Categories
Name List
doctype
category
property
Categories
Tags
Tag List
property
Tags
Iteration
Iteration
value
filled
hide
Source
Result
Sort Key
hide
Teaser
Image Added
hide
Section
show-title
false
title
Description
The page editor provided by Confluence makes it very easy for any team member to create and edit wiki pages. The projectdoc Toolbox contains the Section Macro to define sections as part of a document.
Define Sections
The editor is a very intuitive tool that allows to create headings with short cuts.
But there is no construct that defines a section as an entity. Confluence has the Excerpt Macro to mark content for transclusion, but this content does not handles the notion of a header.
Part of the projectdoc Toolbox is the Section Macro.
The macro defines a section with a title, which may be show or hidden. The section is defined at a given level or the level is deducted from the context.
Title and body are added by the author. If the body of a section is empty, we cannot connect this information to the corresponding title.
The content from the editor:
Since title and body are part of the Section Macro, we can define that a section is not rendered as long as the body of the section is empty.
The content from the editor:
The rendered content in the view:
Panel
My Heading One
My Heading in One
Some text.
My Other Heading in One
My Heading Two
The rendered content in the view:
Panel
Section
title
My Heading One
Section
level
2
title
My Heading in One
Some text
Section
title
My Other Heading in One
Section
title
My Heading Two
Every section, regardless of being empty or not, is rendered. The design of from the template author, created to support the page author, is rendered for the reader. The reader has no benefit from this. To the contrary: the view is cluttered with no-information fragments.
Only sections with content are rendered. As a consequence template authors may define any number of sections to help page authors to create content conforming to a given document type. The reader of the document is not bothered with headlines and empty section body. The view is clutter-free while the editor shows the document structure.