Excerpt heading issue

[gael vigouroux]

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.

Cheers.

Gaël

[Robert Reiner _smartics_]

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.

[gael vigouroux]

Thanks Robert, I will give it a look

[Nic Brough -Adaptavist-]

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?

[Robert Reiner _smartics_]

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!

[Nic Brough -Adaptavist-]

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.

[gael vigouroux]

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