Render only with Content

Sections are a handy tool for template authors to define the basic structure for document types. Since sections are only visible when they actually have content, they are a perfect tool to guide page authors creating content. Readers do not have to read titles without content.

Render dependent on ...

The content of a section can be rendered dependent on

• Roles (any group a user is part of)
• Privileges (authenticated or write-access)
• Document Properties
• Space Properties

This makes it easy for template authors to define sections that are only visible under given constraints.

Drag-and-Drop

Since a section is a macro it can be easily moved around a document with its content. It can be made part of another section or moved up some levels.

While moving, for Confluence servers version 5.8 and up, the heading level is automatically adjusted to the location of the macro. This includes the section (and transclusion) macros inside the moved section.

Transclusion

The automatic leveling of headings is also very handy when sections are transcluded (aka used as excerpts). At the target location a transcluded section at level 1 may be transposed (including its children) to level 3.

Since sections have identifiers (which default to the section title) and may be tagged by arbitrary string sequences, it is easy to specify them for multi-transclusion (aka multi-excerpts).

one=1
two=another replacement
something=else

Delegate Document

A special form of transclusion is the delegate document. A document may reference another document to transclude properties and sections. If a section is empty in a delegating document, it transcludes the section's content with the same title automatically.

Delegate documents can be used to annotate information or transclude a complete document, typically of the same doctype, to another space.

The delegate document is specified with the Document Properties Marker Macro. To transclude properties, they need to be flagged with the delegate property control.

Search Result

When selecting documents with the Display Table Macro, sections may be selected like properties to be rendered in a table column.

The example shows three columns. The first and second column shows properties, the third the description section.

Heading Numbering

Sections support heading numbering. Numbering may be switched on at document or space-level by the use of the Enable Heading Numbers property.

HTML H1/H2 deferred

If you cannot decide whether your top-level sections start with h1 or you want to reserve h1 for the title and start with h2, then sections are for the rescue. Simply define at space-level at which section-level your sections should start.

Use the space property Heading Starting Level to control the base level of document headings.

Remove Decoy Text

Finally, not every section requires the title to be displayed. The function of some sections is deferred from the position or its visual representation. Therefore the title can be suppressed by a macro parameter.

See No need to render the Section Title for more details!