A Quick Way to Manage Multiple Excerpt Macros

[Jaime B_]

Hello Confluence Support Team and People,

I am writing documentation for our software on confluence. I have a excerpts glossary with multiple (+50) excerpts, because a lot of pages have similar but not always the same content. Making sure every single one is named correctly and the content corresponding is, is a burden.

Is there a easier way to edit the name and content of these, than going on every singe one, edit the name and have the side window open and close over and over and over and over again?

Thanks

Edit:
I would love if for example it was not a pop-up/side window that opens but the name above the excerpt edit ready and a checkbox directly below or smth like that.
Like this for exsample:

There is no need for this:

[Arkadiusz Wroblewski]

@Jaime B_  Hello

What I’d do to make it manageable:

1) Best practice: stop keeping 50 excerpts on one page
Create “source pages” instead (one term/topic per page, or at least per section). Put the content in a normal page + one Excerpt, and then use Excerpt Include everywhere else.
Result: you edit once, and it updates everywhere. No more opening the macro side panel 50 times.

2) If you need a glossary-style setup:
Make each glossary entry its own small page and use an index page to link to them (or roll them up). It’s way easier to maintain than a mega-page full of macros.

3) If you absolutely must keep them on one page:
There’s no great bulk tool. The only “less painful” approach is to reduce the number of excerpts (group them into fewer, larger excerpts), so you’re editing 10 blocks instead of 50.

[Jaime B_]

@Arkadiusz Wroblewski Thank you for your answer.

Your first approach is exactly what I am trying to do. Have one source page and then using the include excerpt macro everywhere else. But I still have to update their names maybe from time to time with the documentation and page growing.

Your second approach just relocates the problem with en-masse editing of macros to more smaller pages, not really solving the problem here.

I have tried your third approach before coming to this solution. Hence I am using tables of content on most pages, it is not possible to have larger excerpts, because the titles are not always in the same header layout. A different problem is that most of them are more dependent and modular, therefore not this option sadly also does not work for me.

Appreciate the help regardless! :)

[Arkadiusz Wroblewski]

@Jaime B_ 

Totally get it  if you’re already doing the “source page + Excerpt Include everywhere” pattern, then the real pain isn’t reuse anymore, it’s that the excerpt names keep needing maintenance as the docs evolve.

What usually works best in that situation is to stop treating excerpt names like human titles and start treating them like stable IDs. In other words: pick a naming scheme that never needs to change (something boring like snippet-auth-001 or ui-login-banner) and then keep the human-friendly title as a normal heading inside the excerpt content. Your documentation can grow and wording can change, but the identifier stays stable, so you never have to go back and rename macros just because the phrasing changed.

Confluence Cloud doesn’t really give you a nice “bulk edit excerpt names” UI, so if you truly must rename lots of them, the only real “en masse” approach is doing it via the REST API by editing the page storage format and updating it back, which is doable, but it’s a technical workaround and not something most teams want to rely on day to day. That’s why I try hard to design the naming so it doesn’t require renaming in the first place.

So short version: keep using the source-page approach, but make excerpt names stable and permanent, and let the visible headings/text carry the documentation meaning. That’s the easiest way to make this stop being a recurring chore.

Haha, I knew it, everyone who works with documentation has to deal with this.
By the way, are you using Scroll Documents? It offers some helpful tools for deploying documentation.

[Jaime B_]

@Arkadiusz Wroblewski 

Thanks really for the help. I will try your approach, I already had something similar but not quite the same.

We don't really have any addons. Its mostly what Confluence it self has to offer (which I fear is quite frankly not enough and not at all satisfying). This documentation is more a hub of many help and explanation articles I am trying to sort and make accessible for other employees  to use.

After all that is done, there maybe will be something for external people to read, but its more a working progress then anything else.

BTW: I had some fun and added a really quick mockup how it could easily look like (in my eyes) without sacrificing usability.  

[Arkadiusz Wroblewski]

@Jaime B_ 

You´re welcome and if you need any help, don´t hesitate to reach out :)

[Kris Klima _K15t_]

Hi @Jaime B_ 

I recently wrote an article on using images on Confluence - one part deals with creating image libraries using excerpts. The underlying principles are the same for any content.

Among other things... you can experiment with Databases (see the article) - you can configure a DB to display an excerpt - limitation is that only ONE excertp per page can be shown in a DB but if you use one excerpt per page... a database is great.

Another trick would be using a specific label (or even a custome status) for pages with excerpts / insert excerpts. This will create a proxy for excerpt / insert pages which you can easily track in Content Manager or in Databases.

Last but not least... I'm going to bookmark this conversation to post a new answer when the time is right ;) 

[Jaime B_]

Hi @Kris Klima _K15t_

I have read  through the part you mentioned. It is interesting and I will keep it in mind for when I am going to use and pictures to my document.

Thank you for the advice :)