Site announcement

We are switching off article comments on this website. Read about the upcoming changes to Atlassian Documentation.

Documentation for Confluence 5.7.
Documentation for Confluence Cloud 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.

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

65 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)

        1. Two years on so I fear I may not get a reply but worth a shot.  I am trying to do something very similar to this, and just can't quite figure out the code.  I want to put an excerpt-include macro into a template.  I need to tell the macro that the page whose excerpt it should include has a title that is identical to a text-data field elsewhere on the template, named 'findingspage'.  So something like

          right?  But I think I'm missing a step somehow.  Can anyone help me?

          1. Hi Fiona,

            If the text field is present in the "target" page then you should be able to access its value using the same syntax in my comment from Sept 14 2012 - just replace page:title with page:<name of text field>

            Hope that helps,

            Charles

  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.

       

    2. Hi, I created a multi-excerpt macro which allows having multiple excerpts on a single page and it's available for free! You can download it from here multi-excerpt-macro.

      Cheers!

  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?

     

  24. Is this a know issue that when we Excerpt include, the Confluence topic headers they appear correctly in the page.

    However when you click the link the drop dead since they don't have correct link location and actually the topic headers are directed to the included page. 

    eg

    In using the Excerpt Include | <confluence link page>

    confluence link page <heading 1>   dead link

    confluence link page <heading 2>   dead link

  25. We are also using excerpt and excerpt include. On the  original page, I insert a link to a specific heading on that page (Insert > Link > Advanced. In the link field, enter "#HeadingTitle"). Then, I use the excerpt include macro, and the link doesn't work. I've tried the following to fix it:

    1. Inserted an anchor on original page. This will not work on the include page.
    2. Inserted "#HeadingTitle." This will not work on the include page.
    3. Inserted "Page Name#HeadingTitle." Confluence automatically strips out the current page name and saves it as just "#HeadingTitle." As a result, this does not work on the include page.

     

    1. Hi Maulik and Carla, 

      Links to headings and anchors are quite tricky to get working.   Can I ask, are your links to headings or anchors linking within the excerpt or to pages outside the excerpt? 

      What I did was go to Link > Advanced and enter  Page Name#anchorname  or Page Name#HeadingText   (Note that the page title contains spaces but you need to remove spaces in the heading text (e.g Heading1)) and it worked fine when the excerpt was included on another page. 

      The links will not work if you have not specified the page title that the heading or anchor appears on. 

      1. yes, it is tricky (and I didn't get it to work either.)

        Let's say you have "Page1" and it has an anchor or header like "a1".

        So the link address would be page1#a1, internally reflected as page1#page1_a1 or similar.

        Then page1 would be included in page2.

        If we want to create a link internally within page2 which points to a1 (in the included page1), it's not working because

        it would expect an anchor page2_a1 in this page but in fact it is page1_a1.

         

         

        so, I would assume this will never work, besides if Atlassian creates something smart to make it happen.

         

        Another scenario. Assume page2 includes a toc macro. The TOC code will include the headers of the included page1.

        But when you click onto such links within the toc, nothing happens (because the link address is page2#page2_a1 instead of page2#page1_a1

      2. The reason to use excerpt is to link the headings outside of the pages. 

        Confluence is already creating the headers when you have Headings in the same page.

        However if you like to assemble the headers to external page that's where I use excerpt include.

        Rather easy thing to do than going on Link -> Advance path was copy all the link header from the page you need and paste them in destination location.

        This works pretty fine with minimum effort. Ofcourse every time I change/add/delete the headings I have to make the similar update everywhere else where I have done the copy-paste.

        Hope someday Confluence makes this fix so we could use excerpt include efficiently.

      3. Rachel,

        I appreciate your answer, but it doesn't work.

        1. Create anchor named "my-anchor"
        2. Link > Advanced.
        3. If I enter Page Name#my-anchor as you suggested, Confluence automatically strips out Page Name so that only #my-anchor appears.
        4. I have also tried multiple variations of the page name, and they always kill the link:
          • PageName#my-anchor (removing spaces as you suggested, but this doesn't work)
          • Page+Name#my-anchor (like in the page URL, but doesn't work)
          • https://wiki.domain.com/display/space/Page+Name#my-anchor (goes to the right page but not the anchor)

        I just got the link to work: https://wiki.domain.com/display/space/Page+Name#PageName-HeadingTitle, however, this refers the link to the original page (where the Excerpt macro is) rather than the Excerpt Include page.

        1. Hi Carla, Sorry i see your dilemma now, and I don't know of a way to make the links direct anywhere other than the original page (where the Excerpt macro is) as this is where the anchor / heading is.  Sorry!

  26. I want to include a ImageMap but the links in the ImageMap work only if the "Remove Surrounding Panel" option is not enabled. Is this behavior a bug or a feature.

    How do I document an ImageMap in one place and use several times?

    1. Hi Peter, you might have more luck using the Include Page macro.  I haven't tried it out myself but it might work (the downside to this is if your image map lives on a page with other content - in which case you will probably need to create a page just for the image map and then store it at the root of the space and include it that way). 

  27. Headings in an Excerpt Include do not contribute to the Table of Contents.

    1. Hi Bradley, I've just tried this out in Confluence 5.6, and the headings in my excerpt are shown in the Table of Contents on the page containing the Excerpt Include macro. 

      Which version are you using?  Perhaps it is a bug that has been resolved.

      1. Hmm. OK just checked my pages again and it is working as you say. :/ AHA found it. I was in Preview mode whilst editing the page.

        1. Ah yes, some macros do work unpredictably in the preview, especially if the page has not yet been saved. 

  28. I have created a bug:

    https://jira.atlassian.com/browse/CONF-35383

    If you update the content of the excerpt macro, then the exerpt include macro WILL not update the contents no matter what! even if you delete the macros and recreate them ... the excerpt macro include will amazingly display the original content.  As if it was just a screenshot.

  29. I have also created a new feature request:

    CONF-35384 - Excerpt Macro show more-info-link New

    to have a "more info" mini button/text on the excerpt-include so that if the user wants to read more he/she could click there and the original page where the contents of the excerpt-macro come from is opened.  Othewise I have to create a text with a link myself for every exerpt-macro.

  30. I have also created another feature request to make it formal (if it isn´t so already)

    CONF-35385 - Able to create unlimited excerpt-macros in a page. New

    And, like other users have suggested, you should be able to create more than one excerpt-macro in a page.  Save it with a unique id and then make reference to them from excerpt-insert-macros anywhere.

    One of the points of confluence is to allow users to feel at ease when accessing data.  And to make the data easily available.  Hence you should be able to create as many excerpt-macros in the same page with different content.

    1. We could certainly use this with our site.

    2. Hi Jorge, I created a multi-excerpt macro which actually does that! And it's available for free! You can download it from here multi-excerpt-macro.

      Cheers!

  31. The new inline comment functionality recently upgraded in Confluence doesn't seem to work with Excerpt Include blocks of text.

    Attempting to comment content that is part of an Excerpt responds with the error message

    We can't add your inline comment; the section you highlighted may contain a macro or user mention. Try highlighting plain text.

    I'd prefer it operate so that commented selections are maintained with the text and page associated to the Excerpt block.   Comments should be visible and accessible on all Excerpt Include references to the original content.

    This adds high value when you are showing a collection of excerpts on a centralized page and soliciting feedback from a particular audience.

    1. Hi Matt,

      Thanks a lot for the feedback; it's great to get the benefit of your real-world use of inline comments.

      I'd suggest raising an improvement issue so that we have a record of it, and we can gauge the demand for something like this.

  32. Hi,

    Is there a "find excerpt include" available?
    I'm looking for a way to find ALL the pages where my excerpt is included.

    1. Hi Martin, 

      To find out where a specific page with an excerpt on it is included, to go ... > Page Information - all pages that the page is included on will be listed in the incoming links. 

      To find out all pages that contain the excerpt-include macro itself, you can search using this syntax macroName:excerpt-include* this will list all pages that use the excerpt include macro (but won't give you info about what page is being included). 

      Hope this helps.