The projectdoc Toolbox provides a lot of macros to create documentation. It also replaces two macros provided by Confluence. The Excerpt Macro and the Page Properties Macro.
Confluence provides a number of useful macros. But if the Page Properties Macro does not support all your requirements and the Excerpt Macro without multi-transclusion is too limited, you may want to have a look at the projectdoc Toolbox.
This tip shows, that using the projectdoc variants of the two macros not not more complicated than the Confluence originals. But they provide some interesting features for some of your use cases!
The central use cases we talk about in this tip are
- Page Metadata
- Content Reuse by Transclusion
Replacing Page Properties
The first use case is about metadata. How can an author provide metadata on a Confluence page? The answer is properties!
The Document Properties Marker Macro is similar to the Page Properties Macro. The macro expects a table with property keys and values. Different to the Page Properties Macro there is a third column for property controls.
A document property requires a name (first column). It may or may not have a value and it may or may not have a control.
While the Page Properties Report Macro renders the information provided by the Page Properties Macro, the projectdoc Toolbox provides a collection of macros to fetch this information. The one that comes close to the Page Properties Report Macro is the Display Table Macro.
Here is a selection of macros that render document properties.
| Title | Short Description | Typical Usage |
|---|---|---|
Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided. | Run a query and render properties as columns of a table. | |
Lists references to projectdoc documents in a list. List contain names and optional short descriptions. | Like the Display Table Macro, but hits are rendered as a HTML list. | |
Lists references to projectdoc documents in a list. List items are defined by templates referencing properties. | Like the Display List Macro, but with more control over properties to render. | |
Renders the value of a property of a document. | Renders a single property value from a single document. | |
Renders a template with property references. | Renders a collection of property values from a single document. |
The document properties specified on a space homepage are space properties. They can also be accessed with the Display Space Property Macro.
You may know that page properties are accessible via a REST API (rest/masterdetail/1.0/detailssummary/lines). Currently this API only provides read access. The free Web API Extension for the projectdoc Toolbox provides read and write access to document properties.
Compare Features
Page Properties and Document Properties provides an overview over the features provided by the Confluence macros and projectdoc Toolbox macros.
More details with screenshots on Working with Properties.
Replacing Excerpt Macro
The second use case is about reusing content from one page from a number of other pages.
The Excerpt Macro allows to define content on a page for reuse. The content can then by displayed in another page. The projectdoc Toolbox calls this feature transclusion. The content is defined with the Section Macro (if it has a title and a body) or the Content Marker Macro (for any other part of a page that needs to be transcluded).
A cool feature of sections is that they keep track of their heading levels! You may transclude a section from anywhere into another section and the level of the section headings is automatically adjusted!
While the excerpt macro may only provide one content on a page for reuse, the projectdoc macros may be used any number of times and provides some enhanced transclusion features.
To render the content on another page, Confluence provides the Excerpt Include Macro. The projectdoc provides the Transclusion Macro to do this. But transclusion (especially with sections) is provided by a number of other macros.
| Title | Short Description | Typical Usage |
|---|---|---|
Transcludes content from a document marked with the content marker macro. | Transclude (multiple) content from one document. | |
Renders transcluded content fetched from documents of a result set. | Specify a query and transclude content from all documents in the result set! | |
Add-on to extend the projectdoc Toolbox to integrate remote information systems. | Provides a collection of macros to transclude content from remote servers. |
Compare Features
Excerpt and Transclusion provides an overview over the features provided by the Confluence macros and projectdoc Toolbox macros.
More details with screenshots on Working with Transclusions.
