Table of Contents
- Ability to seamlessly transfer content between multiple pages and spaces
- Reduces need for rewriting boilerplate documentation
- Can be transferred inline with current content or in a resizable block
- MultiExcerpts can contain text, images, Informational boxes, Flow Boards, JIRA issues, and more
The MultiExcerpt function is a two-step process involving two macros, both of which come with purchasing the MultiExcerpt app from the Marketplace:
- Creating the MultiExcerpt key containing the content you want to leverage by reusing/displaying in other locations
- Inserting the MultiExcerpt Include to reuse/display the excerpted content
Difference Between Multiexcerpt and Multiexcerpt Fast
- for legacy pages you should prefer the "Fast" macros
- for new "fabric" pages you should prefer the regular macros (Multiexcerpt, Multiexcerpt Include) because there is no speed advantage in the Fast macros on new pages and dynamic macros have limitations
In a past Confluence version Atlassian made changes to the rendering of pages which slowed down page loading for pages with several MultiExcerpts or MultiExcerpt Includes. MultiExcerpts are "static" macros and, for pages created with the old legacy page editor, page rendering was blocked until all "static" macros were ready. We resolved this issue by implementing the MultiExcerpt Fast Excerpt and MultiExcerpt Fast Include macros within the MultiExcerpt app. The "Fast" versions are based on dynamic Connect app technology that does not block page rendering for pages created with the old legacy page editor.
Fast forward to today and Atlassian has introduced a new page editor (a.k.a. the fabric page editor). Pages created with the new page editor do NOT block rendering for "static" macro processing. It is not necessary to use the "Fast" (dynamic) versions of the MultiExcerpt macro for new/fabric pages. In fact, it may be preferable to stick with the "static" MultiExcerpt and MultiExcerpt Include macros for new/fabric pages because the Fast macros have some limitations due to the nature of dynamic macros (rendered in an iFrame).
As an added complexity: there are many behaviors of new/fabric pages that are undesirable and are inconsistent with the behaviors of legacy pages. In some cases you may be forced to use a legacy page in order to get a feature or behavior that has not been implemented or does not work in the new/fabric pages. When you are forced to use a legacy page you should prefer the "Fast" versions of the macros but beware that they come with some limitations: for example, if you nest a Confluence Table macro inside of a multiexcerpt then table sorting will not work in the "Fast" version because the iframe containing the content does not have access to the CSS styling of the containing page and Confluence's Table macro depends on the CSS styling of the containing page. In a case like that you must choose the simpler, but not as performant, "static" macros.
For information on how to tell the difference between an old page and a new page, see Confluence Cloud documentation.
- Which editor does your page use
- How to get legacy pages enabled for your Cloud instance
- Change to your content is in your hands
- Learn about Confluence Cloud editing improvements
Fallback Permission Handling
The "Fallback permission handling" parameter in the MultiExcerpt macros is used to provide a fallback permission check in some scenarios such as exposing Confluence content in Jira Service Desk (JSD).
A system user, a.k.a. "app user", exists for 3rd party apps like the MultiExcerpt app.
When "Fallback permission handling" is enabled for a MultiExcerpt then, ONLY for situations where the user cannot be found, the app user will be used to access the excerpted content when a MultiExcerpt Include macro requests it.
Most of the time you will NOT need to enable this parameter.
An example of a scenario where it could be necessary to enable it is when using a MultiExcerpt Include on a page that is exposed on Jira Service Desk (JSD). Due to Atlassian bugs, users who are not in your basic profile in JSD will be unable to see content that is included via a MultiExcerpt Include.
Create the MultiExcerpt key
The MultiExcerpt macro is rendered inline.
There are two MultiExcerpt Fast macro options - inline or block
- Select the MultiExcerpt Fast Excerpt (Inline) or MultiExcerpt Fast Excerpt (Block) or MultiExcerpt
- Give the MultiExcerpt a name, then click Insert
The MultiExcerpt key is displayed on the page
- Add the content you wish to be included throughout multiple locations (different pages or multiple times within the same page). You can insert text, images, Informational boxes, Flow Boards, JIRA issues, and more.
- Publish the page
Insert the MultiExcerpt Include
- In edit mode on the page you would like to display your MultiExcerpt key content, select the MultiExcerpt Fast Include (Inline) or MultiExcerpt Fast Include (Block) or MultiExcerpt Include
- Add the MultiExcerpt Name and the Page it's located on, then click Insert
You must have published the page with the MultiExcerpt on it before it will render in Preview
- If the included MultiExcerpt is in another space you can see the name of the space when you hover over the page name(s) in the Page dropdown that is auto-populated as you type a page name. The value of the Page input will be prepended with the space key for the other space when you select the page in the dropdown.
- The MultiExcerpt Include displays while the page is in edit mode
- In view mode, your MultiExcerpt Include displays exactly how it looks in the MultiExcerpt
Inline vs. Block Examples
Inline content allows for the excerpt to be inserted inline with the content around it
Block allows for content to be inserted in a resizable block
View Mode After Saving Page
Importing a Space or Copying Pages Containing Multiexcerpts
The Multiexcerpt app requires that an excerpt be visited by viewing the page it is on in order to create the index that includes need in order to find the excerpt.
For scenarios where a space is exported/imported or copied, or scenarios, where a page tree is copied the indexes for the excerpts, will not be built because the pages have not been visited yet.
Until the pages with the excerpts on them are visited the includes will not be able to find the excerpts.
Visit all new pages with excerpts on them after you copy/import a space or page tree.
This behavior will be improved for usability when MEPOD-71 is released in a future update. After that is delivered the indexes will be created automatically without requiring visitation of all excerpt pages.
There is a limit on the number of MultiExcerpt Includes that you can use on a single page with satisfactory rendering times. This is due to a combination of the capabilities of web browsers, Confluence, and the MultiExcerpt Include macro.
There are many variables to consider so there is no specific limit but if you are approaching 100 includes on a page you are probably pushing the limits of your web browser, Confluence, and the MultiExcerpt Include macro. If you are approaching 150 you are probably past the limit.
We are currently considering approaches to increase the performance of the MultiExcerpt macro to allow even more includes. However, if you are using large numbers of includes on a single page then you may want to reconsider your page design.
Migrating MultiExcerpt from Cloud to Server or from Server to Cloud
There are MultiExcerpt apps for both Confluence Server and Confluence Cloud. There is a migration path for either direction:
|Content by Label|
|Content by Label|