Reusing sections typically includes the transcluded content to match the document structure of the transcluding document. The projectdoc Toolbox does this automatically.
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.
