Reusing sections typically includes the transcluded content to match the document structure of the transcluding document. The projectdoc Toolbox does this automatically.
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.
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.
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).
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:
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.
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.
Related information to sections and their use in transclusions.
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.