Documentation for Confluence 5.4.
Documentation for Confluence OnDemand and earlier versions of Confluence is available too.

Skip to end of metadata
Go to start of metadata

The Excerpt Include macro is used to display 'excerpted' (that is, a segment of) content from one page in another.

The paragraph below shows an example of an Excerpt Include macro, containing content from an excerpt which we have defined on the Excerpt Macro page. On the Excerpt Include macro below, we have set the options to show both the title of the page and the panel surrounding the content.

Excerpt Macro
Define a part of a page as the page's 'excerpt' which can then be displayed in another page.

Using the Excerpt Include Macro

To add the Excerpt Include macro to a page:

  1. In the Confluence editor, choose Insert > Other Macros.
  2. Find and select the required macro.

Speeding up macro entry with autocomplete: Type { and the beginning of the macro name, to see a list of suggested macros. Details are in Using Autocomplete.

To edit an existing macro: Click the macro placeholder and choose Edit. A macro dialog window will open, where you can edit the parameters of the macro.

Parameters

Parameters are options that you can set to control the content or format of the macro output. Where the parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro browser, it will be listed below in brackets (example).

Parameter

Default

Description

Page Containing the Excerpt
(default-parameter

none

Type the name of the page that contains the excerpt to be displayed. You can use an excerpt from a page in the same space or another space in the same wiki.

When you type the name of the page into the Excerpt Include macro dialog, Confluence will offer a list of matching pages, including those from other spaces.

Alternatively, you can type the space key followed by a colon (:) and the page name, like this:

SPACEKEY:Page name

This parameter is unnamed in wikimarkup.

Remove Surrounding Panel
(nopanel)
 

false

Determines whether Confluence will display a panel around the excerpted content. The panel includes the title of the page containing the excerpt, and the border of the panel. By default, the panel and title are shown.

Code examples

The following examples are provided for advanced users who want to inspect or edit the underlying markup for a Confluence page. 

Macro name: excerpt-include

Macro body: None.

Storage format example

Wikimarkup example

 

 

  • No labels

40 Comments

  1. Is it a bug or a feature that the excerpt-include statement does not get updated when the referred page is renamed? (smile)

    1. Hi Graham,

      Thanks for reporting this. There is an improvement request currently being tracked at the following:

      The improvement request mentioned that when a referred page is renamed, the {include} and {excerpt-include} macro that refer to that page is broken.

      You may want to cast a vote to the improvement to increase its popularity and also add yourself as a watcher to receive any updates.

      Regards,
      Choy Li

      1. you might all save yourself a bunch of work if you make sure, like is done with the third party plugins, that the KNOWN bugs associated with each feature are listed on the bottom of the documentation page related to that features.

        it will:

        • keep customers informed of what works well and what doesn't, which will keep customers happy
        • reduce comments about known bugs
        • encourage customers to look for and report bugs properly rather than by email
        • reduce your workload in answering and redirecting people
  2. It would be a neat enhancements if this macro could work by collecting excerpts from pages with a specific label (like the blog-posts macro does). Then people could use the excerpt macro in their labelled templates, and dynamically collect the excerpted info (like Summaries or Definitions) onto a master page without having to manually enter in all the page numbers.

    Should I file an enhancement request for this, or is there one already existing that I can vote for?

    Thanks,

    Carrie

    1. Hi Carrie,

      I have found a similar improvement request that is currently being tracked at the following link:

      The improvement request above suggest Confluence to have the ability to allow excerpts when listing content with a particular label. If there are any similarities with your situation, please cast a vote to increase its popularity and add yourself as a watcher for future updates. Also, you can add a comment to the improvement request above to share your concern with the participants within the improvement request. If that is not an option to you, you may want to create an improvement request at our JIRA Issue Tracker to truly reflect your requirement.

      Regards,
      Choy Li

  3. It would be extremely helpful to enhance EXCERPT INCLUDE with a parameter to specify named areas on other pages, and then allow EXCERPT INCLUDE to pull in Form Fields from pages created using templates.

    That way, different users could see different aggregated views into the data.

  4. I found the use of 'Excerpt Macro' as the example for the name of the page containing the excerpt a little confusing and had to read the small print.  May I suggest that you use a different excerpt-containing page name example?

  5. Hi,

    A number of people have commented on the restriction with the include-excerpt macro that inclusions cannot be made from content in another space. I also faced this issue, and with the help of David Peterson and the CustomWare Reporting plugin, found the following work-around:

    You can swap the "> excerpt" part for "> body" to return the whole page if you wish.

    Of course, if you change the page title of the target page, you do need to remember to update the parameters in this macro manually.

    In Confluence 4.x, the report-info macro takes the following parameters:

    Key: value:content "spacekey:somepage" > excerpt

    Source: blank

    Render: Rich text

    Hope this helps,

    Charles

     

    1. Anonymous

      Hi Charles,

      Pretty simple but terribly efficient....(wink)

      thanks for the tip. That open some nice perspective...

       

      Sincerly,

      Michael

    2. Anonymous

      Yes Charles, that helps a lot.  I like so many others on here was pulling my hair out trying to get an excerpt from another space, and your method works beautifully.  Thanks,

       

      Matt Smith

    3. Anonymous

      Awesome!!! We were looking for a solution like this!

       

  6. Anonymous

    Is there a way to have an exerpt include in a page, but have that exerpt include be minimized, so it doesn't take up much space unless it is actively being looked at?  I am thinking something along the lines of the Code Block macro, but for an exerpt from another page. What I am doing is making a summary page that collects a lot of data for a variety of products.  I would like to display this data on this summary page without it being overwhelming.  Thanks for any advice.

    1. You can embed your Excerpt Include inside an Expand macro to achieve this. It also works the other way around (i.e. the Excerpt definition can contain an Expand macro)

       

      1. Anonymous

        That's awsome, thank you very much Simon.  That macro does exactly what I was looking for.

  7. Hi all,

    Could I ask you for your support in resolving following challenge, please?

    I would like to use the excerpt-include macro in a child page to automatically include the excerpt defined in the parent page and this without hardcoding the parent's page title...

    Already tried "{excerpt-include: {page-info:title|page=@parent} }" However, this only results in the page-info macro correctly returning the parent's title, but that value is then not being picked up as a except-include parameter.

    Thank you in advance for your much appreciated assistance!

    Cheers, Edgard

    1. Hi Edgard,

      My recommendation would be to use the Reporting plugin here, so you can inject the parent page name into the excerpt-include macro. This would need to be wrapped with a report-on macro (to support the injection) and then your excerpt-include would need to be this:

      Regards,

      Charles

       

      1. Thanks for the prompt response and the expert advice Charles! That did the trick indeed... (smile)

  8. I would like to include the text from an excerpt within a Code macro block.  Is that possible?  What I'm getting now is the literal "excerpt-include ..." expression.

    Thanks!

  9. is this macro currently broken? I can't see any way to edit the parameters.. the only thing i can choose when clicking 'edit' is "Hide Excerpted Content"

    1. Per Franck - what version of Confluence are you running?

  10. Anonymous

    Is it possible to use the excerpt and excerpt-include macros within a numbered list? We have 6 pages that have different first steps but all end with the same last steps. It would be nice to be able to just include an excerpt with those ending steps, but adding excerpt-include pushes the list in 2 levels and includes the numbering of both, so that text from this:

    # text . . .

    ## text . . .

    {excerpt-include}

     

    looks like this:

     

    2. text . . . 

       a. text . . . 

          i.1. included text (instead of b.)

  11. The excerpt-include macro breaks when there is a forward-slash in the page title that you're trying to include. The page is returned in the available result set, but when included, returns a "Excerpted page does not exist" error.  Is this a known issue?

  12. When attempting to grab excerpt content from another space, my excerpt-include macro only shows the text "undefined". However, when I edit the macro, all of the correct content from the external space appears in the Preview. Is there something I may be setting up incorrectly? 

  13. Is there anyway to embed custom information such as images to the excerpt once it is on the local page that you want it on? I want to create a level of similarity, but then on some pages I need to add a bit more customization with text and pictures. Anybody know how to do this?

    Thanks

    1. Now you're talking less of an excerpt and more of a "template" and for that I would suggest Writing User Macros.  With those you can have your similarity, but at the time that you add it to page, you can pass it parameters like an image or custom text just for that invocation of it.

      1. Thank you David, I'm going to try that now.

  14. On the page with the included excerpt is shown the title of the page containing the excerpt.  That's great. 

    Is there a way to make that title a link back to the page containing the excerpt?

    1. Hallo DFoxgrover

      There isn't a way to link back to the page, when the page is in view mode. When you're editing the page, you can click the macro placeholder to get a link to go to the included page.

      I hope this answers the question!

      Cheers, Sarah

      1. I have the same need.  Can you please make it an option to have the title in the panel be a link to the referenced page?  I end up having to put a link to the page inside the excerpt it's self so people can click to see the full page.  This often turns out looking weird because you have the title twice.  

        1. I think thats a great idea – most often when I use the macro, I actually put a link to the originating page somewhere outside the macro, either before or after it stating where the excerpt came from in case they want to click for more information.  I would like to see the Excerpt Include plugin code put in Github or something and let people tweak it and Atlassian can fold it in.  

          Here is an example:

          Interesting Heading

          {excerpt from another page here}

          More Info: Link to Page of the Excerpt

  15. Anonymous

    The macro does not work with pages that have a forward -slash, it simply cannot find the page: "The page X/Y could not be found.". Will this be solved any time soon?

  16. Anonymous

    Hi,

    I wrote some text and I want to have the excerpt macro behind the text but it puts the macro in a new sentence.

    So it's like this;

    Blablabla
    (excerpt include)

    But I what I want is this;

    Blablabla (excerpt include)

    so that it stays in that sentence and not starting in a new sentence.

    I am  using Confluence 4.3.7

  17. Anonymous

    I want to include a JIRA issue macro in the excerpt and using Child Display with show excerpts have the JIRA issue show. Will only show text though in the excerpt (sad)

  18. When I want to excert-include a page from another space I get always 'page not found'.

    I tried the following.

     

    We don't have the report-info and the report-on macros.

  19. Anonymous

    Since v.4, the excerpt gets embedded into <p></p> (regardless of the inline/block setting of the excerpt macro: the doc correctly states that this setting impacts only the appearance of the excerpt in its own page).  Due to these paragraph marks, it's not possible anymore to show the exceprt as part of a sentence on another page, nor to have it displayed nicely together with the page name when using macros such as "Content by label" and "Page tree".  When will this be fixed?

  20. nope doesn't seem to work for me - I can create an Excerpt on an older page in the space and then include the excerpt on another page. I cannot include Excerpts from newer pages. Is there some sort of indexing required before the excerpts can be included? It works fine from the older pages. All are in the same space.

  21. Anonymous

    I would really like the ability to have multiple excerpts on a single page and tag them somehow so that the excerpt include could specify which one we want.  I am building status reports and want to pick out specific sections for different views of the overall status.  Is there any plan to make this improvement?

     

  22. Anonymous

    I would also like this ability - two scenarios where this would prevent trouble: we have to create an entire new wiki page for single-sentence excerpts. We also have a dictionary page with multiple excerpts embedded in it. So, it would be much easier just to create the dictionary page and slice it up into different, reusable excerpts.

     

     

    1. Hi Anonymous, just letting you know this is an open issue, and you can follow up on it at ADVMACROS-148. Alternatively, you may find a third-party plugin on Atlassian Marketplace which meets your requirements.

       

  23. I have several excerpts with 2-10 lines of short (20 character) lines of pre-formatted text I want to be able to reuse. They are all entered with shift-enter to prevent paragraph spacing. When I try including them I get unwanted spacing between lines. Sometimes I have the excerpts adjacent and sometimes there are pre-formatted lines before and/or after them.

    Ideally I'd like these in a table. where I can compare different combinations of lines.

    How can I prevent paragraph formatting being applied?