RFC-50: Let users easily interact with AND configure macros in the Editor

RFCs are a way for Atlassian to share what we’re working on with our valued developer community.

It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.

Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!

RFC dates:

  • Publish: May 10, 2024
  • Discuss: May 21, 2024
  • Resolve: May 31, 2024

Summary of the project

Our goal with this RFC is to get your feedback on a proposed solution to make it clear and intuitive for users to both interact with AND configure macros within the Editor. We’ve found that making macros more functional in the Editor can improve their adoption, and we want to continue bridging the gap between Editor and Renderer functionality.


First, some definitions. Confluence has two primary page modes today:

In the Editor today, macros have very limited functionality. The primary limitation we want to focus on solving in this RFC is as follows:

  • Many macros are designed to be interactive, i.e. the user can click on them to trigger their experiences. Think buttons, cards, links, diagrams, etc. that can be clicked.
  • Macro interactivity is not currently available in the editor (besides a select group of Atlassian-built macros like Table of Contents, Child pages, etc). For most macros, there is a “glass pane” over them that prevents them from being interacted with. Due to this “glass pane”, when macros are clicked in the Editor, instead of triggering any interactive elements within them, the macro is simply selected and the user is presented with an editing toolbar.

Unfortunately, just removing this “glass pane” does not fully solve the problem. While removing the glass pane makes the macro content interactive, it becomes unclear how a user would trigger the editing toolbar in order to configure the macro.

Let’s use the Atlassian-built Create from Template macro, which is a button a user can click to create a new page with a certain template, as an example.

Current state experience: when a user clicks the Create from Template button macro, they instantly create a new page.

Let’s say the user is editing and we’ve removed the glass pane from the macro to make it interactive.

If the user clicks the Create from template button, then it will trigger the macro’s interactivity, creating a new page with a template. But, how might the user actually select the macro in order to configure it (or copy it, delete it, etc)? It’s unclear. Technically, users can already click on the macro name or border that appears on hover in order to select & configure it, but that is not necessarily intuitive. We also heard this directly from partners participating in our live-edit pages EAP where we have removed the glass pane from all macros.

Our goal with this RFC is to get your feedback on a proposed solution direction to make it clear and intuitive to a user how to both interact with AND configure macros within the Editor.

Proposed Solution

To make it intuitive for users to be able to both interact with AND configure macros within the Editor, we are proposing the following interaction design.

When a user hovers over a macro, a selection / configuration control will appear in the top right corner of the macro’s content. That way, it’s clear that:

  • If a user wishes to interact with the macro, they can simply click on whatever they wish to interact with within the macro frame (example: clicking on the button to create a new page from a template.)
  • If a user wishes to select the macro or configure the macro (i.e. to update its parameters, copy it, delete it, etc), they can click on the new selection / configuration control in the top right of their of the macro’s content, which will bring up the editing toolbar when clicked.
  • Note that, beyond these changes, we are also considering introducing a new, separate control to the left side of content blocks in the Editor. This new control will lets users select content (e.g. a heading, a paragraph, a macro) and drag it around the page, or move it with keyboard controls. This control may appear at the same time that the macro configuration affordance is shown to a user.

We recognize that some macros have interactive content in the top right corner of their frame in the renderer today. If we pursue this direction, we will update macro guidelines to recommend that there isn’t any interactive content in the top right corner of the macro, to prevent any potential overlap with this configuration menu button. We definitely want to hear your feedback about this direction.

RFC_Demo_UpdatedDragHandle_DemoConfigMenu (1) (1)
Demo of the new macro configuration control concept in the Editor. Users can both interact with the macro content in the Editor and summon the editing toolbar to edit the macro or take any other actions present in the toolbar today (i.e. copy, resize, delete the macro). Note that the toolbar shown in this gif is an exploratory concept, and a first version release is likely to use the toolbar that exists in the product today.

Implications for Apps

These changes would apply to all macros when viewed in the editing experience:

  • Macros built by vendors or customers using Connect
  • Macros built by vendors or customers using Forge
  • Macros built by Atlassian

No changes would be made to macros when viewed in the rendered experience.

Updates/work would be required on your end as a result of these changes if your macro has interactive content in the top right corner of the frame that would need to move so as not to overlap with the configuration control. Otherwise, no updates/work would be required.

What about macros that are bodied extensions?

These changes will apply all types of macros, including bodied extensions. However, bodied macros still have an additional challenge where they currently only show their nested content in the editor, and the “rendered” view cannot be displayed in the Editor. This RFC does not cover how we plan to bridge that gap.


  • What feedback / concerns do you have around this updated macro interaction design?
  • Are there any other areas, use cases, etc that we are missing?

Next Steps

After hearing your feedback, we plan to make any necessary design iterations to make sure we’re best meeting the needs of our shared customers. Once your feedback is incorporated, we will update with our final direction when the RFC is resolved at the end of this month.

1 Like

Hi @DavidMichelson, thank you for sharing the ideas and soliciting feedback.

We are in the group of vendors that have app menus in the top right corner of our macros. (e.g. below is a signature block with the impacted app menu highlighted in red)

For us, and potentially other apps that have rich interactive content, the macro […] button and menu showing overtop the context of the interactive app (once the glass pane is removed) could be confusing to users whether they are working “within” the app or are managing the Confluence macro.

Thinking out loud, Confluence already has a popup macro label showing outside and above the macro body. Perhaps if that that label became part of the manage macro toolbar it would be more clear that the […] menu applies to the macro envelope, not the app itself?

Rough composite image below to illustrate the idea, highlighted in green. Centered in the illustration, but could be left, center or right.

Thank you
Chris C
Digital Rose


If possible: remove the glass pane, keep the current toolbar but display it on hover.

Current UX:

  • Click: toolbar appears outside the frame and displays the menu options.
  • Edit flow: click >> click pencil icon

Demo UX:

  • Hover: toolbar overlays the frame and hides the menu options.
  • Edit flow: hover >> click the ellipsis icon >> click edit

The demo worsens the UX, obstructs the macro, adds an additional click to editing, and hides that edit option behind an ellipsis dropdown. For any macro that requires configuration you’ve hidden the single most important button users need to click.


Second @nathanwaters suggestion to make the macro configure “pencil/gear” an always visible button and not hidden behind the elipsis.

Pop out macro menu below the macro works well for small macros. For macros that are vertically tall (e.g. we have a Search Documents macro that is full page height), menu at the bottom could be pushed off the screen.


I feel like the obvious solution to the “top right” problem here is to show the “…” button on hover outside of the macro, similar to how you propose there is a drag & drop button on the left. This way, no existing macros should be affected.


+1 to @PhilipFeldmann 's suggestion. So basically display the same action bar on hover that appears on click today.

PS: We also have a few macros where the visibility of the rendered content will be affected by having a “…” button on the top-right (or anywhere overlayed on the macro for that matter)



Just wanting to add that it would also very painful to us when the “…” button appears to the top right, all other proposed solutions seem decent, I like the one @Chris_at_DigitalRose proposed most.

I do think many vendors would be unhappy especially with the top right location - we try to mimic the design of Atlassian to have a more immersed experience, and consequently put our primary icons to the top right, too. :wink:


1 Like

The goal is to make macros a more native part of the Confluence experience, same logic for live editing pages :+1:.

Will this do anything to solve the problem where vendor macros do not have the same treatment as Confluence macro. For example when a user highlights text using our Word Count app the content within vendor macros is not counted, but native macros are.

As least allowing this for Forge built macros.

1 Like

Thank you all so much for your feedback! We are keeping tabs on each post and will come back with iterations/updates near the resolution date.

To answer this question specifically -

Will this do anything to solve the problem where vendor macros do not have the same treatment as Confluence macro. For example when a user highlights text using our Word Count app the content within vendor macros is not counted, but native macros are.

I don’t believe the problem you outline will be included in this project. But, thank you for the example - do you have any other examples / any more specifics on this issue? Would love to learn more.

@DavidMichelson the core issue is that native Confluence macros and those created by vendors do not always get the same ‘access’ for lack of a better term. It can feel like an iFrame, and we all know iFrames are no longer used as they are more like hacks devs think are good enough rather than what should matter - solutions users want.

My thinking is that with Forge dealing with security concerns for clients (Atlassian runs the server side and with data residency option) this could all Forge macros (and Forge apps more generally) to get a ‘deeper’ integration.

I also think macros have become a lazy hack to add features. Atlassian needs to think or ways to avoid having to use macro altogether. By design we built Space Content Manager 100% in Forge with no macros.

Live edits feel like the start of a major improvement for average users (who are used to Google docs not edit-publish modes) that could open a Pandora’s box of innovation for vendors.

1 Like