Use the Section Macro to define sections. This tip introduces the macro by listing its features.
The Section Macro defines sections with the following features.
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.
The content of a section can be rendered dependent on
This makes it easy for template authors to define sections that are only visible under given constraints.
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.
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).
Placeholders
When transcluding content, the Transclusion Macro allows to apply placeholder replacements. Add the following to the body of the macro
one=1
two=another replacement
something=else
And the placeholders ${one}, ${two}, and ${something} will be replaced by the values 1, another replacement, and else.
Consider to use the Module doctype to define self-contained information for modular documentation. The doctype makes it obvious to team members that the content is used for transclusion only.
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.
Delegate to Category
For instance an author may want to delegate to a Category document in another space. This way the category of another space is valid in the context of the transcluding documents space. The documents belonging to the category, which are displayed on the category page, may be restricted to the local space. That is: all properties and all sections except the one showing the documents of this category in the current space are transcluded from the delegate document.
The delegate document is specified with the Document Properties Marker Macro. To transclude properties, they need to be flagged with the delegate property control.
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.
Sections support heading numbering. Numbering may be switched on at document or space-level by the use of the Enable Heading Numbers property.
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!
The following macros are related to sections.