projectdoc Toolbox

Use the Section Macro to define sections. This tip introduces the macro by listing its features.

Parent
Audience
Level of Experience
Expected Duration
30 min
Type

Every projectdoc document consists of properties and sections. Sections are a tool to structure pages. They are created by the ise of the Section Macro.

This short tip lists features of this macro to support template authors, page authors and readers.

Contents

Features of Sections

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.

Render dependent on ...

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.

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).

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.

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.

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.

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!

Resources

The following macros are related to sections.

Content Marker Macro
Marks a piece of content within a document. This content can be referenced for transclusion.
Transclusion Macro
Transcludes content from a document marked with the content marker macro.
Transclude Documents Macro
Renders transcluded content fetched from documents of a result set.
Display Table Macro
Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided.
documentation-json-uri
The URI to a JSON document containing the URLs to the documentation for the blueprints.