Intro to Content Reuse
Content reuse is a key principle in technical writing in general. It enables writers to ensure consistency across different content, helps increase efficiency, and saves both time and money.
To make content reuse work properly with versioned content, Scroll Versions comes with its own version of the Include macro, (called the Include+ macro) and the Excerpt Include macro (called the Excerpt Include+ macro). These make reusing content within versioned spaces a snap.
Include+ and Excerpt Include+ macros work only in spaces with Versions or Translations
The Include+ macro
The Include+ macro is an overhauled version of Confluence's Include macro. It highlights included content, shows you the source of the content on mouseover, and also displays the other pages that also use this content.
The Include+ macro is integrated with the concurrent versions feature, meaning the corresponding version of the included content is displayed. For example, a page for target version 1.1 will include the target version 1.1 of the included page. If the 1.1 version is not available, the macro will fall back to an earlier version of the included page.
How do I use it?
You insert the Include+ macro as you would any other macro. When you do, you can select a page to include. The selected page's content will be included where you inserted the macro. Once you activate Versions in a space, any existing Include macros will be automatically converted into Include+ macros. You don't need to do anything manually.
To view the source of included content, the Highlight Include feature must be activated. You can mouse over included content (highlighted in a light gray box) to see the name and version of the source page. You can also click the source page to go there directly. You can find the Highlight Include setting in your user's Scroll settings.
Furthermore, you can check whether the page you're on is included anywhere else (in your currently selected version) by clicking Include Info next to the breadcrumbs area.
The current implementation is based on the following assumptions:
Included content is defined on pages in an include library.
Included pages are not usually directly accessible to readers.
Include library (same space)
A best practice when reusing content is to use an include library, a section of your space set aside for content you will reuse. By creating an include library, you have easy access to the entirety of your reused content. Create a new page called _Include Library, and view in hierarchy and drag it to the top level (the same level as your space's home page). Create a child page for each block of content you plan to reuse, and prefix each name with a leading underscore (for example '_Content Reuse'). With this approach, your include library won't be visible to readers, as by default, top-level pages aren't displayed in the tree view. If you want to also see top level pages, you can define that in your Scroll Versions User Settings.
Reusing versioned and translated content from other spaces with the Include Library
To reuse content from other versioned and translated spaces, an extra step is required. In the space where you want to reuse content, you must manually configure which versioned and translated spaces you want to include from.
This is because versions and languages need to be mapped in order for the Include+ macro to know which version or language to include from.
Add spaces to include from
Note: you need to have space admin permissions in both the current space and the space you want to add.
Navigate to the space where you want to include content.
Add a space to include from by clicking Space tools > Scroll add-ons > Administration > Include Library > Add space
Find the space that contains the versioned or translated content to be included.
Go through the steps in the dialog and map all versions and languages that you want to include from
Once the versions and languages have been mapped and the space has been added, you can use the Include+ macro to reuse content both from the current space and the added space.
See how publishing works when including content from other spaces.
Limitations and constraints:
You can only add spaces that are not using include Library themselves.
You cannot add spaces that have variants.
Reused pages need to contain all attachments they use themselves.
Reused pages can not reuse other content themselves.
Make sure all links on reused pages are reachable also where they are included
Excerpt-Include+ macro doesn't currently support Include Library. See VSN-4188
The Excerpt Include+ Macro
The Excerpt Include+ macro is a modified version of Confluence's default Excerpt Include macro, reworked to function correctly in versioned spaces. It is used to display sections of one page in another.
How do I use it?
Include any content you want to duplicate in a normal Excerpt macro, and then insert an Excerpt Include+ macro on the page where you want it to be duplicated.
Things to keep in mind:
The Excerpt Include+ macro resolves the included page through its current working version and language. For example, a page in target version 1.1 and language English will include the content of the source page in version 1.1 and language English.
Like the normal Excerpt Include macro, the Excerpt Include+ macro will always include the content in the first Excerpt macro on the source page. So only one Excerpt macro can be used per page.