One of the key features of Confluence is the radiation of information or how you can easily share information across the environment, avoid duplication and copy-paste, and reduce the steps to update information. There are multiple ways of doing that, it could be by embedding pages into other pages or using macros like Excerpt, or if you can add marketplace apps, you can also use MutliExcerpt.
In the article The Purpose of the Atlassian Marketplace, I explained why it is essential to keep an eye on the out-of-the-box functionalities and the Atlassian Marketplace to maximize our platform's usage. In this particular case, I will explore the macro Excerpt's functionalities included with Confluence, its limitations, and the big brother offered by the Marketplace that will go beyond basic features. I think that MultiExcerpt macro should be part of the product, but the Atlassian Ecosystem exists to provide opportunities to entrepreneurs and solutions to the users. When you use styles to create a document, you can change how the whole document looks with just a few clicks.
Let's consider that you have products and a confluence page for each one to host all the product-related information. For this example, I will use two products, a can of beans and a can of sardines. (in your case, think about your own "element," software modules, apps, events, team members, projects, etc.).
In a plain confluence page, we can host all the information related to the product, including images of the packaging, logo, bar code, etc. It will be a rigid block of data, and, if we need to share the information, we will have to do it as one artifact. Confluence provides a mechanism for that by just sharing the link to the page or embedding it into another page or blog post.
For a single page, we probably achieve our goal, but the whole purpose of this article is to generate content that we can reuse and share. Let's explore some scenarios.
What if we just want to share a piece of that page?. Well, the solution is easy, we can use the macro Excerpt, that will allow us to specify a piece of content that could be used with other macros (like include excerpt or reports by labels). So far so good! We added a little flexibility to our rigid block of information.
What if we need a couple or more pieces of information from that page?. Well, here is the bad news, out of the box we can have just one excerpt macro per page, sorry about it!.
Having the content as one big block of information will block the way you radiate information. Of course, using child pages could help, but you need to be careful about how many pieces you will use to build additional pages, it could seriously affect your performance.
The main benefit of using Excerpt or MultiExcerpt is that you need to worry about just one place to host and maintain the information.
We can address our “What if... #1” business needs with the Excerpt Macro (full documentation is here).
It is easy to use (just keep in mind that it is just one per page). Add the macro and then place the content inside of it. It can be any type of content, including images. In the example below I am placing inside the macro the label picture.
This page is the "container" of the information that we will reuse in other pages.
To use that information on a different page use the macro: Excerpt Include and the content will be populated. Any change on the host page will be immediately reflected in all the pages using the information. Good improvement and reduction of data duplication.
Excerpt macro can be also used with other macros as parameters. (In this case please keep consistency on the type of content placed inside the macro). See below few examples of re-purposing content by using Excerpt.
As you can see above, we are just showing the content inside the macro Excerpt, and we are not using the entire page content. A little bit of flexibility added to our information sharing experience.
We can not address our “What if... #2” business case the macro Excerpt, but it could be satisfied by splitting the content in a certain number of children pages. (probably too many if you need little pieces of information).
Going back to the products that we are using as an example, you can see on the picture of the can label or sardine can packaging that we have one image that could represent the full product. It is probably ok for our purpose, but (as in many products) what happens if we want to use just pieces of it based on specific needs.
The pieces of information in the product packaging like
How can we use just some pieces of information?
The marketplace app that includes the macro MultiExcerpt and Include MultiExcerpt address this particular need.
(Note: other macros use just the regular Excerpt, so you will probably need to use that one for the essential piece of information and then use MultiExcerpt for additional data)
The recommendation is always to use the Excerpt Macro first and then add other information blocks using MultiExcerpt. In our example, I will keep the label inside the Excerpt macro and the rest on MultiExcerpt blocks. The page containing the macros and information is the only one that we will need to update, all the pages consuming the data will update the content in real-time.
In the page structure below, you will see three blocks of information
Page with the Excerpt macro and MultiExcerpt macros.
The new page will show the information that is inside the "Details" MultiExcerpt macro.
We will use now the content that is inside the Ingredients MultiExcerpt
Yes, Our final page will look as the original one, so there is no difference there for the end-user, the key benefits are how we can radiate that information in other areas of our Confluence instance and reduce maintenance time.
Below I am using the macro Include Page selecting Page 3 that contains both Excerpt and MultiExcerpt macros.
(Note: this approach apply Nested Macros that is not available in Confluence Cloud)
Both, Excerpt and MultiExcerpt macros could be used within the Page Properties macro and then use the information with the "Page Properties Report". In order to do that we will need a couple of tweaks to our original pages:
1. adding a label (product) and
2. adding the Page Properties macro that includes the information as a table.
To demonstrate this Bonus Tip we will have two pages with the same structure, one for Beans and the other one for Sardines.
Page Beans with label "product"
The MultiExcerpt macro is developed by Artemis Software and it is available in the marketplace. The oldest version published is from 2011 but I remember using it since 2008. Keep in mind that the main purpose of creating content in Confluence is to share it and repurpose it. The article is based in the server version but the macro is available for Cloud and Data Center.
Excerpt macro is included with Confluence and it has the limitation that you can use just one per page. Excerpt is powerful as you can use it with other macros like Report by Label. I hope you can use it and enjoy the experience. Have Fun!
Fabian A_ Lopez _Community Leader - Argentina_ Florida_ California_Community Leader
Connect with like-minded Atlassian users at free events near you!Find an event
Connect with like-minded Atlassian users at free events near you!
Unfortunately there are no Community Events near you at the moment.Host an event
You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events