Documentation for Confluence 5.5.
Documentation for Confluence Cloud and earlier versions of Confluence is available too.

Skip to end of metadata
Go to start of metadata

The Excerpt macro is used to mark a part of a page's content for re-use. Defining an excerpt enables other macros, such as the Excerpt Include and Blog Posts macros, to display the marked content elsewhere.

You can only define one excerpt per page. In other words, you can only add the Excerpt macro once to a page.

Using the Excerpt Macro

To add the Excerpt 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.

To add reusable content to the macro:

  1. Add your content inside the Excerpt macro placeholder.
  2. Choose the macro placeholder to see the options panel, and select the option to Display on new line or to Display inline. The default is to display the content of the macro on a new line. If you choose the inline option, the content of the macro will form part of the same paragraph as the text preceding and following it. Note that this option affects only the page that contains the Excerpt macro. It does not affect any pages where the content is reused.

Screenshot: The Excerpt macro placeholder and options panel

Gliffy Zoom Zoom Excerpt 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

Hide Excerpted Content
(hidden

false

Controls whether the page content contained in the Excerpt macro placeholder is displayed on the page.

Note that this option affects only the page that contains the Excerpt macro. It does not affect any pages where the content is reused.

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

Macro body: Accepts rich text.

The following additional parameter is available in storage format and wikimarkup. It performs the same function as the options panel in the editor. 

Parameter nameRequiredDefaultParameter description and accepted values
atlassian-macro-output-typeNoBLOCK

Determines whether the content of the Excerpt macro body is displayed on a new line or inline.

Available values:

  • BLOCK – Displays the content of the macro on a new line.
  • INLINE – Displays the the content of the macro as part of the same paragraph as the text preceding and following it.

Note that this option affects only the page that contains the Excerpt macro. It does not affect any pages where the content is reused.

Storage format example

Wikimarkup example

  • No labels

44 Comments

  1. This is a great macro, but seeing as there is only one allowed on a page it defeats my purpose for it.  What I am trying to do is essentially "pivot" the view of the information depending on the audience.  For example, if audience A wants to see instructions from a systems view and audience B wants to see the same info but from a process view, you might have the systems page address each system in order and tell how to use it in each business process, then on the process page you might use the same content but order the content by process and display excerpts from different systems pages in the appropriate process sections to display the how each system component is used in each business process.  So you would have

    System Page 1

    Process Page 1

    System Component 1

    Process A uses system component 3, so excerpt system 3 instructions

    System Component 2

    Process B uses system component 4, so excerpt system 4 instructions

    System Component 3

    Process C uses system component 2, so excerpt system 2 instructions

    System Component 4

    Process D uses system component 1, so excerpt system 1 instructions

    System Component 5

    Process E uses system component 5, so excerpt system 5 instructions

    Is there a macro or technique that can help accomplish this?

    1. Hi, Steve. First off, sorry if this is a little too late. I may not truly understand your requirements, however, I think that this is feasible if you separate those processes into different pages and use the {excerpt} or {include} macro in the main page. Writing a Writing User Macros might help too, in case you would like to apply some logics to the page.

    2. Steve,

      I understand what you're trying to do and we're trying to accomplish the same thing.  I'm trying to convert our RoboHelp 7 docs into the wiki.  RoboHelp has a feature called conditional text.  You can tag a topic (page) or any text with a conditional tag, then use the conditional build tags in the output (online help or PDF) for different audiences.  For example, we might have one topic, and we use conditional tags in different parts of the topic for the administrator or end user.  So we're reusing topics instead of copying them, and there's less of a chance for error because we're only editing that one topic.

      The problem with the Excerpt macro and the "hidden" parameters is that even anonymous users will be able to see the hidden text in a search.  I hope someone posts a solution.

      1. Anonymous

        I thought I saw a macro, where you could define them (e.g. excerpt macro - topic 1, excerpt macro - topic 2) - but I don't think it is compatible with 3.1 ? This would be a VERY useful feature.

        1. Hi,

          the multi-excerpt macro does help regarding multiple excerpts on one page. You can name each excerpt and include it on other pages of any space.

          Disadvantage of this plug in is that renaming a page will break the link. You have to keep all manually updated.

          cheers

          1. I do not see the multi-excerpt marco... I have version 3.3. Any ideas on why not?

            1. sorry I did not set this page to be watched by me(wink)  You dont see the macro because it is not free of charge.

              You will find it here: https://studio.plugins.atlassian.com/wiki/display/CMEP/Confluence+Multi-Excerpt+Plugin

              Cheers.

  2. Anonymous

    why do you not write the wiki markup for these macro's? Some of the earlier documentation do but you've stopped doing it lately. Please give us examples of the markup, not just the arguments/parameters in a grid.

    1. Thanks for your question!

      This page is part of the  documentation for Confluence 4.0, which was released recently. Confluence 4.0 no longer supports wiki markup for writing pages or for inserting macros -– there is a brand new editor! So, it is no longer relevant to include wiki markup in the macro documentation for this latest version. As you've noticed, that information is still available in the documenation for earlier versions, which is available using the links at the top left of the window.

      Please add a comment to the following page, if you wish:

      http://confluence.atlassian.com/display/DOC/Giving+Feedback+on+Confluence+Releases

      regards,

      Paul

      1. Anonymous

        How are we to use macro's in our templates then?

        Seems to me wiki markup/documentation shouldn't be phased out until all features can use the new system

      2. Anonymous

        How are we supposed to create templates in Confluence then?

        This is a recurring and extremely irritating oversight!

        1. Anonymous

          Experiencing same annoyance here.

          1. Hallo all

            I have now added the documentation for the wiki markup and storage format for this macro.

            Cheers, Sarah

  3. Anonymous

    Is there any equivalent plug-in to Multi-excerpt for Confluence 4.0/4.1? I really want this capability to keep from creating thousands of one-line pages for Learning Objectives, but I need to use both lists of objectives AND single objectives on other pages. I asked my Confluence admin to install multi-excerpt, but they are getting ready to upgrade to 4.1, so the artemis plug-in will not be available.

    My searching has not turned up any equivalent plug-in from any vendor, free or commercial. Can anyone help?

    In hopes of an answer,

    Lori P.

    1. We have the same issue, of needing to excerpt multiple selections from a single page with 4.0/4.1. Would be great if this enhancement were on the road map.

  4. Anonymous

    +1 for that requirement!

  5. In 4.1 When I use the Excerpt Include Macro it does not work 

    The Include Excerpt was created in Space 1 and Excerpt Include Macro used in Space 2 - both spaces have the same permissions. But it seems I can't use the 'remove surrounding Panel' button or the macro does not work. I wish to include an excerpt from one space page into another space page without the surrounding panel. 

    I also included the space key in the macro and it works so I know that not the issue 

    Any insight is appreciated – this is driving me nuts because I need to include excerpt from one space into another. 

     

    1. I'm having the same problem. The "Show Excerpt" Boolean doesn't seem to work.

  6. Anonymous

    any of you guys know how to do this one in wiki markup?
    I tried {excerpt}with no luck
    
    Thanks
    1. Hallo there Anonymous

      Which version of Confluence are you using? I've just tried {excerpt} on this wiki, and it works: The autocomplete successfully converts it to a full Confluence 4 macro placeholder.

      Here's the syntax for Confluence 3.5: Excerpt Macro

      If you're using Confluence 4, it may be that you've run into a bug. Please would you let me know what happens when you try to insert the macro?

      Cheers, Sarah

  7. Anonymous

    Man I have been working on using the Excerpt and Excerpt-Include macros.  It has been so long since I used it and the documentation in here no longer has good examples - as well as the nice Wiki Markup options no longer available (well it may be available but we no longer have access to it with our latest upgrade) I no longer love confluence as must as I used to.  I am disappointed that I have to go to an external site to get good examples of the code in use to use as a trigger.

    And as I said - I no longer like the loss of my wiki markup option as this was my default view and not the rich text editor.

    1. Hallo Anonymous

      I have now added the code examples for this macro.

      Cheers, Sarah

  8. Hi there, if I'm writing a blog entry I have the option to display an excerpt. Unfortunately all links of the excerpt are transformed into plain text - unclickable. Is there a trick to keep links clickable? Best regards, Alex

     

  9. Hi,

    is there a way to control the "Display on new line"/"Display Inline" using wiki syntax? 

    I use this macro in a Global Template (not rich text), and the generated new page always use the Display On New Line setting. The result is that we must edit this manually all the places it's used (and it's qute a few...).

    I would really like to be able to set Inline by default.

    Ola.

    1. Hallo Ola

      I've just tested this, and it is possible to use wiki markup to control the inline / new-line display, using the atlassian-macro-output-type parameter. Available values are BLOCK and INLINE.

      Example :

      {excerpt:hidden=true|atlassian-macro-output-type=BLOCK}
      This is the *text* I want to reuse in other pages. This text is inside an Excerpt macro.
      {excerpt}
      I have now documented the wiki markup and storage format codes for this macro, and added the links to this page.
      Cheers, Sarah
  10. also I want to know if we can use wiki syntax to make the excerpt hidden

    1. Hallo Gerald

      Yes, you can use wiki syntax to hide the excerpt. I've added code samples for this macro. Here is an example using the hidden parameter in wiki markup:

      This is the *text* I want to reuse in other pages. This text is inside an Excerpt macro.
      {excerpt}
      Cheers
      Sarah
  11. Anonymous

    Support for multiple named excerpts (which would allow this to work for dynamic content displays which have 'show excerpt') would be extremely useful. Right now, one has to work around it in a very cumbersome workflow with specially labeled pages with individual excerpts on each. Not very user friendly. And yes, I know about the commercial plug-in - it just doesn't work with all other macros, essentially rendering it useless. It's not that we couldn't pay, it is just that it wouldn't work...

  12. Anonymous

    I'd really like to include table-driven data (like a Gliffy flow chart) on a page and can't find a single way to do this.  For example, I'd like to pull the text from a cell of a table into a flow chart so that my users only have to update the table, not the flow chart.  I thought the excerpt macro would do it, but it doesn't seem to work, even if I forgo using Gliffy for my chart.  I find it really odd that Confluence doesn't seem to have this capability.  I'm like the 1st guy to include a question here, I want to be able to redisplay my table data in different ways, but I only want to have to update the data in the table so that things don't get out of hand with multiple users.

     

  13. Anonymous

    The excerpt macro is useless and forced you only to include one page and not flexible. I understand you can create multiple wiki pages to achieve multi-excerpt desires. Why bothers to create many wiki pages for similar topics? It doesn't make. Why can't excerpt macro work like the commercial multi-excerpt, where you just create one wiki page with all relevant topics inside this wiki page and use label to include this particular excerpt in other page and not entire wiki page and don't have to create multiple pages for it. It defeats the purposes of using excerpt marcos. Why didn't you think of this when designing the excerpt macro? What is the point of creating this marcos with limit usage and don't update it to be usefulness and tempt us to buy a commercial plugin. I really hate use your wiki software, but I have to because I have no other choice and my company uses all other your products. I use the wiki to make documentation. This is the most useful macro there is and has very little usefulness. 

  14. Anonymous

    The excerpt macro is working partially. I have also installed the languages macro with English, Spanish and Portuguese. What's more, I have the blog-post macro installed so that you can read the excerpts from blog-posts listed on my homepage. The problem is that this last macro doesn't take the excerpt from different languages. This only shows it in portuguese whatever the real language is.

    I tried to quit excerpt from blog-post macro and that's working but by showing the whole blog-posts. So, i need to know what the problem is and be able to show in every language the excerpts from this blog-post macro.

  15. Anonymous

    how do you remove the excerpt macro while retaining the content

  16. Anonymous

    Another vote for multi-excerpt!

  17. I am having trouble with this macro. I excerpted a section from a page in a space, no problem. I would like to place that excerpt on a page in another space. When i use the "excerpt to" macro and type in the original excerpt page name everything seems fine. But when i save, instead of the excerpt appearing, there is an error message that says "page not found." 

    This is weird because it's clear when I am selecting the page in the "excerpt to" macro that Confluence is recognizing the original excerpt page. The system is even putting the space acronym automatically in front of the excerpt page name.

    1. Hi confluence team, does the excerpt macro not work? Can someone pls help me? I can't even get it to work w/i one space. I feel like I am doing everything properly, but no dice. keep getting an error.

  18. Anonymous

    How can I include an excerpt from an arbitrary web page – not a Confluence page?

     

  19. Is it possible to get a list of pages that include my excerpt?

    We have several general diagrams that can be included in pages. I would like to know on which pages each diagram is used.

    Page A:

    • excerpt diagram A
    • list of pages that include excerpt A

     

    Several other pages:

    • excerpt include diagram A
    1. Hi Marcel, Yes this is possible.  Go to the page that contains the Excerpt macro, and choose Tools > Page Information.  All pages that reference this macro (using the Excerpt Include macro) will be listed under Incoming links. 

      Unfortunately the list does not differentiate between ordinary text links that might be on the page, or Excerpt Include / Include macros but it gives you somewhere to start. 

      Hope this helps

      1. That is pretty usefull, thank you Rachel.

        Is it possible to include this information on the page itself in some way without having to go to the page information section?

        1. Sorry, I'm not aware of a way to do that. 

  20. We are currently evaluating Confluence 5.4 and realized that this plugin is even more limited with the new handling of sections. If you are using a layout with more than one column you can only have an excerpt within one of these columns. Any plans for correcting/updating this?

    1. Hi Martin, 

      You are correct, macros can only be added within page layouts, including ones like Excerpt. There are some other options for you however. You can use the Include macro to include an entire page, rather than just an excerpt (which will bring across the whole page layout), or you can use the Section and Column macros instead of a page layout - enabling you to still put layouts within your excerpts (and have more fine grained control of your column widths etc).  Hope this helps. 

  21. I've upgrade a confluence instance from 4.3.1 to 5.5.2 and some functionality now no longer works.

    We have a space where we use an excerpt macro for a summary on each page.  We then use a children display macro to list the pages.  In the settings for the children display macro, include excerpts is ticked. 

    We have links in the excerpts, but when the pages are displayed in the children display macro the entire link address is showing rather than the link text. 

    1. Hi Linden, sounds like a bug. Have raised an issue here  CONF-33881 - Children macro displays full URL in excerpt, not link text Open