Cloud

Contents:

Introduction

https://fast.wistia.com/embed/medias/9xmbptrgl0.jsonp

The MultiExcerpt app performs similarly to the excerpt macro, allowing for excerpts from multiple spaces. 

The MultiExcerpt function is a two-step process involving two macros, both of which come with purchasing the MultiExcerpt app from the Marketplace:

  1. Create the MultiExcerpt key containing the content you want to leverage by reusing/displaying it in other locations. To learn more about creating MultiExcerpt content, click here.
    The following are the available MultiExcerpt macros:

    1. MultiExcerpt Macro

    2. MultiExcerpt (Advanced)

    3. MultiExcerpt (Advanced Inline)

  2. Inserting the MultiExcerpt Include to reuse/display the excerpted content. To learn more about how to reuse MultiExcerpt content, click here.
    The following are the available MultiExcerpt Include macros:

    1. MultiExcerpt Include

    2. MultiExcerpt Include (Advanced)

    3. MultiExcerpt Include (Advanced Inline)

Difference between MultiExcerpt and MultiExcerpt Advanced

Summary:

  • for legacy pages, you should prefer the "Advanced" macros

  • for new "fabric" pages, you should prefer the regular macros (MultiExcerpt, MultiExcerpt Include) because there is no speed advantage in the Advanced macros on new pages, and dynamic macros have limitations.

Explanation:

In a past Confluence version, Atlassian changed the rendering of pages, which slowed down page loading for pages with several MultiExcerpts or MultiExcerpt Includes. MultiExcerpts are "static" macros, and page rendering was blocked until all "static" macros were ready for pages created with the old legacy page editor. We resolved this issue by implementing the MultiExcerpt (Advanced) and MultiExcerpt Include (Advanced) macros within the MultiExcerpt app. The "Advanced" 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. Using the "Advanced" (dynamic) versions of the MultiExcerpt macro for new/fabric pages is unnecessary. Sticking with the "static" MultiExcerpt and MultiExcerpt Include macros for new/fabric pages may be preferable because the Advanced macros have some limitations due to the nature of dynamic macros (rendered in an iFrame).

As an added complexity, many behaviors of new/fabric pages are undesirable and inconsistent with the behaviors of legacy pages. Sometimes, you may be forced to use a legacy page to get a feature or behaviour 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 "Advanced" versions of the macros, but beware that they come with some limitations. For example, suppose you nest a Confluence Table macro inside a MultiExcerpt. In that case, table sorting will not work in the "Advanced" version because the iframe containing the content cannot access the CSS styling of the containing page. Confluence's Table macro depends on the CSS styling of the containing page. In such a case, you must choose the more straightforward, but not as performant, "static" macros.

See Confluence Cloud documentation for information on the difference between an old and a new page. 

Difference between inline and block

The MultiExcerpt Advanced macros provide two options: inline and block. The following table provides the differences between inline and block macros:

Inline

Block

Inline

Block

Inline allows the excerpt to be inserted in line with the content around it.

Block allows the insertion of content into separate blocks.

Edit mode

 

View Mode After Saving Page

 

 

Edit mode

 

 

View Mode After Saving Page

Limitations

Performance

The number of MultiExcerpt Includes you can use on a single page with satisfactory rendering times is limited. This is due to a combination of web browser capabilities, Confluence, and the MultiExcerpt Include macro.

There are many variables to consider, so there is no specific limit. However, if you are approaching 100 includes on a page, you are probably pushing the boundaries 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 increasing the performance of the MultiExcerpt macro and allowing even more includes. However, if you use many includes on a single page, you may want to reconsider your page design.

Â