projectdoc Toolbox

Reusing sections typically includes the transcluded content to match the document structure of the transcluding document. The projectdoc Toolbox does this automatically.

Audience
Level of Experience
Expected Duration
15 min
Type

To make the management of information in Confluence easier, information should be stored in one location and one location only. When there is the need for changing this information it requires the change to be applied only to one location. That is easy from the author's point of view.

On the other side is the reader who needs to see this piece of information in different contexts, that is on different pages. To make this information, that is stored in one location, visible on in multiple pages, the page author uses a tool called transclusion (or excerpt/excerpt include in Confluence lingo). This transclusion provides an invisible link to the content on another page. Whenever the content is updated on its page, this change is immediately (at request time) visible on the pages that transclude this content.

If you happen to transclude a section hierarchy and not just plain text or a graphic with an explaining paragraph, the level of the section titles need to be adjusted to the level in the transcluding page. We call this process of adjusting the heading level 'heading level transposition ' or 'transposition' for short. This feat is done by the projectdoc Toolbox automatically. This short tip shows you how.

The right page transcludes content from the left page using heading level transposition.

Contents

Prerequisites

As prerequisites you should be familiar with the concept of sections, especially the use of the Section Macro. Knowing the concept of projectdoc Document is helpful.

You should also know how to basically use the Transclusion Macro and the Transclude Documents Macro.

Content to Reuse

Suppose an article shows content you would like to reuse.

The section shown in this example is part of the tip Using Space Properties. In this excerpt there is one section 3 with three subsections.

 

Having a topic based approach ideally each page has one topic in a single section. This is certainly a good practice, but in reality author's often struggle to get this right and clean. And even if there is a single topic in a single section there may still be a shallow hierarchy of sections which heading levels need to be transposed.

Reusing Content

Now let's assume we need to include the use cases section on another page. There we have already a section titled 'Using Space Properties" and now need to transclude the content. The section in the page is at level one (the section is not contained in another section) and at position two (there is one section as a sibling in front of this section).

When authora specifiy sections (using the Section Macro) and transclusions (using the Transclusion Macro), they do not need to bother with heading levels or section positions.

The transclusion specifies the page to transclude from and the name of the sections to transclude. In this example this is only one section, but you can specify more sections (either by adding multiple identifiers or by adding one or more tags).

The result is this:

Transclusion Box

 

Note that the transclusion box that is drawn around the transcluded content is only visible to page authors (who have the privilege to edit the page). This box provides quick access to the page (clicking the page title) and also allows to open the page in edit mode (clicking the small pen).

Adding the Section Header

In the previous example we have chosen 'blank' as the target level of our headings. This will remove the toplevel heading. If we want to include it, we need to choose '*'.



Use automatic Leveling

 

You can choose to set the level of the heading in the transcluding page to a fixed value. This is necessary for older versions of Confluence. In the latest version of Confluence the projectdoc Toolbox can manage to derive the level automatically. This is what you should do. Use either the blank or the asterisk value as target level. The fixed level feature will probably be removed in near future.

Moving the Transclusion

Using automatic levelling (either the blank or the asterisk value for the target level heading parameter) makes it easy to move sections around.

Suppose you want the section with the transcluded content inside another section named 'Features'. Simply drag and drop and you are done!

Here is the document in the view.

Multi-Transclusion

For the projectdoc Toolbox multi-transclusion is not only defined to transclude multiple content areas (sections or content marked with the Content Marker Macro), but also transclude from multiple documents at the same time. The use case would be to trasclude the description and resources sections from each glossary item document to provide a condensed view on your glossary.

We do not want to delve into this here, but you you a hint to get started: Look at the Transclude Documents Macro.

Resources

Related information to sections and their use in transclusions.

Content Marker Macro
Marks a piece of content within a document. This content can be referenced for transclusion.
enable-heading-numbers
Controls whether or not section headings should be numbered. The numbers are added via CSS, therefore they won't work for export formats that do not take CSS into account.
Transclusion Macro
Transcludes content from a document marked with the content marker macro.
Multi-transclusion
Describes the technique to transclude one or more content fragments from one or more documents.
Transclusion
Tools to provide or consume content to support reuse.
projectdoc Toolbox Online Manual
The online manual for version 1 of the projectdoc Toolbox for Confluence.
The projectdoc Toolbox for Atlassian Confluence
The projectdoc Toolbox supports agile teams in writing project documentation collaboratively. This is an introduction to use cases for and features of the projectdoc Toolbox.

List of tips related to transclusion.

Agile Documentation
Agile documentation is not another buzzword. There is actually a set of rules to follow which will lead to meaningful documentation. Writing helpful documentation is not easy, but it gets a lot easier with the agile mindset - and with the projectdoc Toolbox.
Content Reuse
The projectdoc Toolbox provides a number of features to help teams to reuse content. Content can be transcluded individually or in form of a multitransclude. Authors can even transclude content from multiple documents in the wiki, effectively combining transclusion with automatic lists.
Impersonator - using Live Templates
A short introduction using the impersonator feature of the projectdoc Toolbox. In this example we examine what to do to reuse a layout defined in another document.
The hidden Section
The Content Marker Macro identifies content that can be displayed using the Display Table Macro. This is a short tip on how to transclude content from a projectdoc document.
Transclude transcluded Sections
Shows how to transclude transcluded content.
Two central Use Cases for the projectdoc Toolbox
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.
Use Display Table for Transclusion References
It is easy to list all pages that transclude a section from the current page. This allows you, as an author, to check quickly if changes to a document that is transcluded, needs changes to the transcluding documents.
Using Placeholders
An overview over features employing placeholders to create a modular documentation.