Showing results for 
Search instead for 
Did you mean: 
Sign up Log in

Next challenges

Recent achievements

  • Global
  • Personal


  • Give kudos
  • Received
  • Given


  • Global

Trophy case

Kudos (beta program)

Kudos logo

You've been invited into the Kudos (beta program) private group. Chat with others in the program, or give feedback to Atlassian.

View group

It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

Excerpt heading issue

This question is in reference to Atlassian Documentation: Excerpt Include Macro

Dear community,

I would like to find a way my excerpt headings to adapt to the structure of my the page where they are inserted (example: Heading 1 of an excerpt inserted below a Heading 2 should be transformed in Heading 3).

Any idea?

Many thanks in advance for your reply.



2 answers

You could do this with the (commercial) projectdoc Toolbox.

Use the Section Macro to define sections with a heading level. Then use the Transclusion Macro to define the target level (or let the macro calculate the level if you use Confluence >= 5.8).

Note that it does not work with headings that are not defined with the Section Macro.

Bias alert: I'm one of the authors of the add-on.

Edit: Make sure that the Confluence page also defines properties with the Document Properties Marker Macro. If you want to try it out, I'd like to recommend to use the projectdoc Blank Document Blueprint.

The article Content Reuse is overview over the transclusion features provided by the projectdoc Toolbox.

Thanks Robert, I will give it a look

Ohh, thank you Robert, I'd not seen that your add-on can do it. In this case, I think there's still a bit of an issue with "how do you know what level to do things at", but with the transclusion macro, it looks like that it goes away because the person using it will have to understand what it's doing properly.

I've got some clients who could really use that (and quite a lott of the other macros).  I hope you don't mind me recommending that they give your add-on a try?

Hello Nic!

I think that what you wrote in your answer is correct. It is quite difficult to discern from HTML code where a section ends and another begins. There are some HTML 5 features that may help, but we cannot assume that these features are widely adopted.

As you already stated in your comment, with the use of dedicated macros for defining content and transcluding content, this problem can be managed. They come at an extra cost: Users need to learn new concepts. Quickly adding a heading with a shortcut (Ctrl-2; quick and easy) is replaced with creating a section macro (also easy, but far less quick).

I'm very happy to hear that your clients could take advantage of using macros in the projectdoc Toolbox! We have learned that customers encounter some difficulties in starting with the projectdoc tools. If you need some help to get started or you have questions for particular use cases, please do not hesitate to get in touch!

We are eager to assist you to get most out of projectdoc!

0 votes

I'm afraid that's not possible. 

It's not really something the macro can solve, even if it were rewritten.  The question is "how does the system know when to shift the headings levels around?"  You could, in theory, code the excerpt macro to look at the text above it and assume that "the highest level of title within the included text should be one level lower than the block I am included in (and shift any others down accordingly)", but how do you tell it when the text should be at the same level, or even be a title in it's own right?

While the question is a good one, and there's really good reasons for doing it (I can think of three documents that it would have been useful in for me this week alone), it's actually very complex to implement and simply hasn't been done because of that.


Hi Nic

Thanks for your answer. I am not a developer but a confluence user and would like my time to use confluence more expensively.

This functionality, as well as the ability to define many excerpt within the same page, should definitely be part of that macro. The way it is make difficult to reuse text.

The idea would not to rewrite the excerpt macro (except for being able to use it many times in the same page), but to rewrite the excerpt include macro. Indeed, the excerpt include macro could parse the excerpt content and rewrite the formatting in accordance to the level to where it is include.

Hope to see that functionality developed soon

Suggest an answer

Log in or Sign up to answer
Community showcase
Posted in Confluence Cloud

Please tell us how you use Confluence space settings

👋 Hi there, a few of us at Atlassian would love to learn about how you use "space settings" functionality in Confluence. A facelift to the space settings is long overdue and we want to start with im...

181 views 6 6
Join discussion

Community Events

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

Events near you