A new approach to Confluence macros is coming to Cloud


The Atlassian Editor team is rolling out a number of sizeable changes to the way macros exist in Confluence Cloud. We’re shipping a new:

  • Configuration experience to help users stay in context when editing macros
  • Element Browser to help users find both native elements and macros (in a prettier way, too)
  • Top toolbar + dropdown to help users insert elements into the editor in a more consistent way

We need you to:

  • Read this blog and understand the impact to you. We’ll be following up in the next ~1 month with another blog with concrete asks for you to dogfood the experience with your app. Note, dogfooding will only be available for partners in the Confluence Cloud: Developer-First Rollouts for Ecosystem App Developers Group".
  • Complete this 1 minute survey re; new browser categories to help us understand if our new proposed categories make sense. Please do so by Jan 15, 2021.
  • Leave any questions or comments on this blog


Extensibility in the Confluence Cloud Editor is critical for a number of reasons. For:

  1. Our mutual customers , it’s how they truly unleash the power of products to service their specific needs. Macros provide users the ability to supercharge their Confluence documents with all manner of wonderful experiences and features.
  2. You as partners , it’s how you create value for our mutual customers, and inherently, how you create a thriving business for yourselves.
  3. Atlassian , it’s how we scale our ability to deliver value to our mutual customers by having more external teams building on the editor.

For all the value the historical extensibility model in the editor provided, it had a number of downsides. For:

  1. Our mutual customers , the UX was at times unintuitive, disruptive, and out of date. For example, when editing a macro, the configuration would appear over the macro itself, making it impossible for the user to see what content they were editing without opening a second tab. Our macro browser also didn’t align to our current design guidelines.
  2. You as partners , could only build macros/apps for a single product, Confluence. There was no opportunity to surface and sell your app in other products’ editors (e.g. Jira’s editor).

What is changing?

With an understanding of the challenges mentioned above, we’ve reimagined and rebuilt our extensibility experience.

A new content discovery experience

We’ve overhauled the old school macro browser, giving it a lick of paint (i.e. aligning it to current design guidelines) and bringing native elements into the browsing experience. We now not only surface existing macros, like the Table of Contents macro, but also surface all other native elements that can be inserted into the editor, like panels and expands. This creates consistency with what is available in our other insert menus such as the slash command. Furthermore, it’ll work in all products, not just Confluence (in the future - more on that later).

Our + menu in the top toolbar dropdown has also been overhauled to look and feel the same as the / command and Element Browser. A search field has been added to the top to enable quick search of macros and native elements.



As part of this new browsing experience, we’ve done research to update the categories in the left sidebar of the browser. We had a belief that the categories didn’t map too intuitively to all the apps. We validated this with user testing and have come up with a better performing list of categories. As a final test of these categories before we implement them, we’d love to get your thoughts on what category you think your app would make sense to map to. Can you please fill out this 1 minute survey to help us make this experience as awesome and intuitive as possible - follow this link to Google Forms.

Contextual configuration

To solve the problem of taking users out of context when configuring their macros, we’ve built extension configuration into the new side panel in Confluence. This aims to provide a far greater WYSIWYG experience for users, enabling them to see the extension they’re configuring whilst configuring it.

As partners, you don’t need to do anything for this. We’ve migrated all your configuration experiences to the sidebar. Note: there are a small group of macros that have custom configuration that won’t initially work in the new configuration panel. For these they will continue to use the old configuration. We have a flag that will recognize when custom configuration is used and will automatically fallback to the old configuration experience. Over time, we will work to define a path forward for these macros as well.

A more extensible editor

One of the big advantages of this new approach, beyond the UX, is the fact that configuration and browsing of macros can happen in any Atlassian cloud product that has the new editor. This theoretically means that you can build a macro once, and sell it to a lot more users across Jira, etc. Unfortunately, we won’t be able to ship this in the short-term as products like Jira still have some issue views that use the markdown editor. If a user were to insert an extension in an issue’s new editor, then someone else were to view/edit it in the old editor, we’d corrupt their content. We’re currently looking at ways around this. We’ll let you know when we’re getting close to launch!

Our rollout plans

As this is a sizeable UX change, we’re going to do a conservative rollout. Stages of rollout are outlined below. Exact dates will be announced shortly on Community. We’re just finalising some dev work and testing on our side:

  1. Rollout new experience internally at Atlassian and on your testing instances through the “Confluence Cloud: Developer-First Rollouts for Ecosystem App Developers Group” for dogfooding. We’ll take feedback and make appropriate fixes over the course of ~4 weeks.
  2. Start progressive rollout to customers. We’ll incrementally rollout over ~4+ weeks.

During this rollout time, we’ll also be sending out communications to our customers about the upcoming changes.

What do you need to do?

We’ll let you know shortly about dogfooding dates where you’ll be asked to test your app. In the meantime, can you please complete this 1 minute survey re; new browser categories to help us understand if our new proposed categories make sense. Please do so by Jan 15, 2021.

As you’re building new apps in the future, please consider the new UX, ensuring that your configuration makes sense in the new model. If we have any gaps with what we’re providing, please also let us know so we can make things better!

We hope you’re as excited about this as we are!

Jonno Katahanas | Product Manager for the Atlassian Cloud Editor


@JonnoKatahanas Thanks for showing how the new macro experience looks.
I’ve got a question regarding page versions: With the current system, a user needs to edit a page in order to change a macro. This automatically generates a new page version.
Will the new experience also change the page version?
And if so, will AP.context get updated?


Hi @JonnoKatahanas,

first of all thanks for this post! Love all the gifs and extensive descriptions, makes it really easy to understand what’s going to happen. :smiley:

While I generally like the look of these changes, they also induce quite a bit of fear in me. I think, most prominently the Contextual Configuration.

I think that’s not really true. It might be a bit too early and speculative but it does sound like in the long run you want all macros to follow this pattern which of course makes sense. I can already see this being a huge problem for at least one of our apps though, which relies a lot on the macro editor being a dialog right now. It also looks like we’re going to lose a lot of horizontal space and will have to trade that in for vertical one. I.e. we’ll have to completely redesign, and potentially rewrite, our macro editors. I don’t think it would make sense to go into details here though - gonna wait for the post you mentioned that should come in about 1 month with that.

Also, be aware that all Marketplace Partners that have macros will have to update all of their screenshots and marketing materials. At least for us this means considerable effort.

Can you share numbers on how small that group actually is? We haven’t built a single macro so far that wouldn’t have required a custom editor, so I’m quite surprised that you’re saying that this is only a small group.

I appreciate that you’ll let custom macro editors stay with the old experience for now, because I’m really afraid of ending up in a situation where we’ll have to support all of these scenarios in our macro editors at the same time:

  • editor v1
  • editor v2
  • editor v2 with the new contextual configuration

I’m excited to hear more about the path forward you’re mentioning, as I think there might be several complications that will only come to light once this new experience is broadly available. Do you already have a timeline in mind for how long you’re planning to support the old experience for custom macro editors in the future, after the Contextual Configuration has been rolled out?

Really excited to hear those exact dates. And thanks for giving us this 4 week window for testing our apps on EAP instances! As far as I can tell, it sounds like once you start rolling out to customers, after about 1-2 months all instances will have received the new experience, making the situation above where we have to support 3 different macro editors unlikely? That would be great.

Generally, I have to say I’m quite thankful that you seem to be sharing this with us so early down the road, giving us some time to prepare. But I must also say that I’m scared to hear more on the technical details and the effort this might cause for us. :eyes:



We are looking to build a marco using Forge. Any information on how, or if, these changes impact Forge.


I want to echo what @sven.schatter has written above, this sounds like a good and much needed step forward for the macro experience, thanks @JonnoKatahanas and team!

I also share the concern about overhead with maintaining macros across the various editors, especially with trying to provide a migration pathway for customers moving to cloud using editor mk1.

I’m really interested in the language that’s being used to describe ‘native page elements’ aka Atlassian Cloud Macros and how they’re being differentiated from vendor macros. Is this intention to provide customers more awareness about what features are built-in vs what have been added? Does calling one an element and the other a macro cause any confusion for the users? Would love to find out more about this.

PS. great response @sven.schatter thanks for taking the time to write and share it!



Dear @JonnoKatahanas,

thank you for sharing the details. In addition to @sven.schatter statements I also would like to add that some of our “custom macro editors” need to perform actions before the macro is inserted/updated (e.g. creating an image, loading a DOI cite). Please consider this during your changes.

Thank you



Hey @marc!

We’re not changing how the page is getting updated or anything on the backend. We’re purely changing the UI. Therefore, page versions, etc won’t change.

Hope that helps!

Feel free to set up a time to chat to me in person if you’d find valuable - https://calendly.com/jkatahanas/editor-extensibility



Hey @sven.schatter!

Great questions (as always) and thanks for taking the time for such a thoughtful response.

Re; partner’s not needing to do anything. This statement was purely speaking to the short-term for initial rollout where we will have the fallback to the old macro browser if your UI doesn’t work with the new config. If your config can exist in the new world, we’ve converted it for you. If it doesn’t, we automatically fall back to the current macro config. Long-term, yes, you’re correct, partners’ will need to design new macros in a way that work in the new UI. That said, we’re 100% aware that not all macros/use cases will be able to exist in the new right-rail config as it is today. We’re still working through how to solve this. Over time, we’ll provide more robust config functionality that supports more complex use cases. In the meantime, we’ll have the fall back in place. We have no near-term plans to deprecate the old config experience. We’ll move to deprecate it once we have a more robust config experience in the new world. I wouldn’t expect this to be in this FY (i.e. before end of June 2021).

Re; updating screenshots. that’s a great callout. I’ll add it to the asks as part of my next rollout message to partners when we’re getting closer to dogfooding.

Re; numbers of macros with custom config. This has been a complicated number to get accurately. It’s been a working assumption based off looking through some of our top apps. Some partners will inherently be more impacted than others. Sending this message out early was partly to ensure we were getting feedback from partners to validate some of our thinking. We’re in the process of having a back-end change that’ll help us identify these custom macros. This change is what will ensure we automatically fall back to old config for those that don’t work. It’ll also help us better identify the number of impacted macros.

Re; supporting multiple editors. The old macro config that we’ll fall back to is the same one as used in Editor v1 (i.e. TinyMCE). For a partner, your macro will either work in one of two config experiences. The old one or the new one. The old one is what exists in TinyMCE as well. The new config only exists in the new editor. After the initial rollout period, at worst, a partner should only ever get into a state of needing to support two editors.

Hope this helps!

Feel free to set up a time to chat to me in person if you’d find valuable - https://calendly.com/jkatahanas/editor-extensibility




Hey @JonathanGithers!

There is no impact on Forge. Forge had already changed the config on their side before we updated anything in Confluence. You can learn more about Forge config here - https://developer.atlassian.com/platform/forge/add-configuration-to-a-macro/

Feel free to set up a time to chat to me in person if you’d find valuable - https://calendly.com/jkatahanas/editor-extensibility


Hey @dlindsay!

Re; maintaining multiple editors, please see my response to Sven :slightly_smiling_face:

Re; language used to describe “native page elements” vs partner macros. We’re intentionally not differentiating when grouping them in categories. What we’ve found is that to a user, they just view using Confluence and its features as a single Confluence experience. They go to Confluence to do a job, and the extensions + native features are there to help them do that job. They don’t care (or want to care) if they’re using an extension or a native feature. They just want to get the job done and will use whatever feature is best to do so. We intentionally want to move to a world where ideally, a user doesn’t need to think about if they want to use a native feature or an app. We’d hope that Atlassian + our partners can provide native and Marketplace experiences that feel like they’re all natively Confluence. This is why we publish design guidelines, etc. From research, the best experiences are ones where an end-user doesn’t know if they’re using a feature Atlassian built, or a partner built. It just feels consistent and familiar.

Feel free to set up a time to chat to me in person if you’d find valuable - https://calendly.com/jkatahanas/editor-extensibility




Hey @andreas1!

Please refer to my response to Sven. If an experience doesn’t currently work with the new config, it’ll continue using the existing one. Over time, we’ll build out the functionality of the new config to support more robust use cases. In turn, over time we’ll move towards deprecating the old macro config to just have the new experience.

Feel free to set up a time to chat to me in person if you’d find valuable - https://calendly.com/jkatahanas/editor-extensibility



Hi @JonnoKatahanas,

We have a diagram plugin. The side panel cannot accommodate a full-featured diagram editor. We tried Forge and its team told us they have no plans to support custom UI in the configuration panel. Now, the connect framework will also deprecate the old macro config. How we can plan for that?

So, are you considering this scenario in your future plan before deprecating the old macro config?



Hey @ashraf.teleb85!

Great question. We 100% know that there are some apps like yours, Gliffy, etc that require more UI space than a config panel on the right. Before we deprecate the existing macro config, we’ll make sure we have a solution for these types of tools (that’s next up for us to figure out). It wouldn’t make sense for those types of free-form experiences to exist in a right rail config.

We’ll let you know when we have a longer-term solution for you. For now, sit tight. The existing macro config you’re using isn’t going anywhere just yet :slight_smile:

Feel free to set up a time to chat to me in person if you’d find valuable - https://calendly.com/jkatahanas/editor-extensibility



Ah, missed your response just before my vacation! Thanks a lot for clearing everything up, Jonno, and answering all those questions. Feeling a lot better about all of this now. :slight_smile:



Is there any news on this change?

We’re eager to understand when we can test this new interface with our Apps offerings.

Hey @jack.graves, we just announced beta testing for partners has gone live!