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.
Include library in the 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
Reusing content from another versioned or translated space is no longer recommended.
Since Scroll Versions 4.5.0, the option to set up an Include Library is hidden per default and needs to be activated manually.
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.
How (Excerpt) Include Macros Convert
If you use Confluence native (Excerpt) Include macros in a space managed by Scroll Versions or Scroll Translations, then there are cases when these macros will transform into (Excerpt) Include+ macros. In similarity, there are cases where (Excerpt) Include+ macros will convert into their native counterparts if used in a space without Scroll Versions or Scroll Translations. These conversions are taking place to ensure the macros are used in spaces where they are compatible.
Below are two tables you can use as reference to get an overview of the macros conversion behaviours.
Excerpt Include+ and Include+ should only be used in versioned or translated spaces, whereas Excerpt Include and Include page should mainly be used in normal Confluence spaces. If you have used Include+ or Excerpt Include+ in unmanaged spaces (spaces without Versions or Translations), then you can use the Fix Include+ macros tool. The tool will help you replace (Excerpt) Include+ macros with Confluence native include macros.
When native Confluence (Excerpt) Include macros transform into (Excerpt) Include+:
Case | Action | Will the macro convert into (Excerpt) Include+? |
|---|---|---|
Activating apps | Activating Scroll Versions in a space by creating a first version. | No |
Editing a page for the first time after creating a first version in the space | Yes | |
Activating Scroll Translations in the space by creating a first language. | No | |
Editing a page for the first time after creating a first language in the space. | Yes |
When (Excerpt) Include+ convert into Confluence native (Excerpt) Include macros:
Case | Action | Will the macro convert into (Excerpt) Include? |
|---|---|---|
Publishing | Publishing a space version from a space without Scroll Translations being used in the same space. | Yes |
Publishing one or all languages from a space translated with Scroll Translations. | No | |
Deactivating apps | Deactivating Scroll Versions by deleting the last version in a space without Scroll Translations. | Yes |
Deactivating Scroll Versions by deleting the last version in a space a space with Scroll Translations. | No | |
Deactivating Scroll Translations in a space without Scroll versions by deleting the last translation. | Yes | |
Deactivating Scroll Translations in a space with Scroll Versions by deleting the last translation. | No |
Content Reuse Reports
In order to keep track of your reused content, there are two reuse reports that can give you an overview of how pages are reused.
Page-level report
The page level report can be accessed by clicking Include info above the page title of the included page.
The reports lists all pages that reuse the current page, including the version in which it is reused by the page. The displayed pages can be filtered by space. The version list is fallback-aware, meaning if the reused page is reused only in one version, but its content is inherited by succeeding versions, all of the version will appear in the report.
The question this report aims to answer is: Which pages in which versions will change and might need re-publishing if the current page is edited?
Cross-space report
The cross-space report operates on the space level as it's designed specifically for setups with external Include Libraries. Access the report for all library spaces of the current space under Space tools > Scroll Add-ons > Include Libraries > Reuse report. To open a report for a specific library space, click the more menu of that space (•••) > View reuse report.
The report lists pages reused from the selected space, along with the workflow state and translation status of the reused page.
Available Settings
Current space: Select the space version (and language) of the current space you want to report on.
Show included pages from: Select the library space you would like to report on.
Hide complete: Hides reused pages that are in the workflow state Complete.
Hide translated: Hides reused pages that are in the translations state Translated.
The question this report aims to answer is: Are all of the reused pages in this version of my documentation ready to be published?