RFC for New Slash Command and Right Rail Element Browser
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!
Dates:
- Publish: 25 Mar 2025
- Discuss: 8 Apr 2025
- Resolve: 14 Apr 2025
Summary
This RFC proposes an updated design to the Confluence editing experience for the slash command menu, element browser, and macro categories. The goal is to improve element discoverability for customers and Marketplace Partners through a consistent, task-based experience and information architecture.
The work will be released in phases. Phase 1 involves minor enhancements of the current experience, while Phase 2 represents a comprehensive transformation of that experience.
Problem statement
Today, the slash command menu and element browser in Confluence is:
- Inconsistent and disorganised
- No logic to how elements, macros, text formatting and AI actions are found
- Vague category labels. For example, the Opsgenie Incident Timeline is listed under Formatting.
- Limiting discoverability of elements
- This has led to a less engaging user experience and hindered the overall functionality of the feature - only 12% of customers use the slash command menu.
- Only 6% of customers click-through from the top toolbar to open the element browser.
- Disrupting the editing experience
- The current element browser lacks the ability to insert, browse and search elements without blocking the editing experience.
Proposed phased solution
We’ve been working with customers to design and test an editing experience that best suits their needs and assists discoverability of elements and macros. The solution we propose is broken into 2 phases:
Phase 1: Modifications to existing experiences
- Toolbar changes
- Removal of the + from the top toolbar - We’re removing all element actions from the top toolbar and instead, introducing a floating + which will sit to the left of the drag handle menu in the editor.
- The plus button opens the existing slash command menu
- Existing slash command experience updates
- A “view more” option to access the element browser from the slash command menu.
Phase 2: All new experiences
- All new redesigned slash command menu
- New modernised UI and UX with new menus
- A “view more” option to access the element browser from the slash command menu.
- All new element browser appears on the right
- Replace the existing element browser modal with a new right rail component that can remain open while a user edits content. This will help customers pick and choose between what they need while editing.
- Updated categories for macros
- Reorder the slash command menu and element browser to include categories and sub-categories that assist with seamless discoverability while editing.
- Include a dynamic section of elements based on usage to surface to offer a more personalized experience of Confluence.
Current categories for macros
When building Confluence macros Marketplace Partners can currently select a macro property that determines where the macro will surface in the element browser.
This is a non-required property. If a macro does not assign a category property, the macro will still appear in the slash command menu and via search for customers who have it installed.
Some current limitations for macro categories:
- Macro categories are not reflected in the slash command menu
- Macros do not appear in the same category as Atlassian elements
- Category names contain overlap, weakening their purpose
Existing macro categories:
- formatting
- confluence-content
- media
- visuals
- navigation
- external-content
- communication
- reporting
- admin
- development
Updated categories for macros
The updated categories offer a task-based way for customers to discover both elements, Atlassian macros, and Marketplace app macros in a consistent experience. They have been through multiple rounds of customer testing to ensure they meet the editing needs of Atlassian customers. They are designed to be both clear enough for customers to find tools quickly while also robust enough to cater to the variety and complexity of the Confluence Ecosystem.
The categories will be reflected in both the slash command menu and element browser to consistently guide customers through element discovery.
Updated categories (from June 2025):
- Essential elements [highly-used Atlassian elements]
- Media
- Structure, with subcategories:
- Connect content
- Search and navigate
- Data and charts, with subcategories:
- Charts
- Labels
- Reports
- Timelines and roadmaps
- Collaborate
- Marketplace app macros
- Atlassian Intelligence [Atlassian elements only]
Interim solution for categorisation changes
We understand that changes can be challenging, and we want to make this process as smooth as possible for you. We will automatically map current categories to new ones based on the category mappings above (Proposed Mappings section). You will have a period of six months to update your category fields, allowing you time to adjust before we remove the obsolete categories from the application manifest.
Proposed mappings for interim solution
You’ll decide which category best suits your macro. We recommend focusing on the primary purpose customers use your macro for.
How will Marketplace macros appear?
- Macros will appear in the “View all” section of each category.
- In each “View all” section elements will appear alphabetically.
Below is a proposed map of how the existing categories link to the updated ones. That being said, selecting a category is not required for macros, and customers will continue to be able to search for your macro as they are today.
| Existing Category | Proposed Category Mapping | Category Definition | Example Atlassian Macros Include |
|---|---|---|---|
| Formatting | Confluence content | ||
| Media | Visuals and images | Media macros enrich content with media, often from a source outside of Confluence. | Blog posts, Card, Carousel, Emoji, Iframe |
| Navigation | Structure | Structure macros help customers arrange content on the page or between different types of content. | Structure, Divider, Excerpt, Layout, Table, Table of Contents |
| External Content | Reporting | ||
| Development | Data and charts | Data and charts macros help customers add or embed data, including reports, charts, or timelines. | Chart macro, Content by label, Content Report, Date, Database |
| Communication | Admin | ||
| Collaborate | Collaborate | Collaborate macros help customers access team-related tools. | @ Mention, Change History, Create Jira issue, Contributors |
| N/A | Marketplace app macros | Marketplace app macros will be for macros that do not have an assigned category. |
FAQs
Where will the slash command menu changes be made?
All updates to the slash command menu will be applied throughout the entire Atlassian platform, guaranteeing that these changes are visible in all products where the slash command menu is currently accessible. As it stands, there will be slight variations in the user interface of the slash command menu across different products. For instance, the slash command menu outside of Confluence will not display the “view more” section at the bottom.
What if my app macro has two categories?
App macros will need to remove multiples and only have 1 category per macro
What if I don’t select a category?
Your app macro will still appear in the “Marketplace app macros” category and in search results
Can my app macro appear in more than 1 category?
An app macro can only be assigned to one category of its choice. However, all app macros will also appear in the “Marketplace App Macros” category, in addition to their chosen category.
What if I don’t update my app macro’s category and leave it with an existing category?
Starting in June 2025, we will implement the interim solution and automatically map the old categories to the new ones. Your app macro will still appear in the “Marketplace app macros” category and in search results.
Can I select a sub category as well?
In this initial release of the new categories, users will have the option to select only a category. However, future updates to the macro property will allow for the selection of a subcategory as well.
Asks
If we go ahead with the new categorisation we would need you to:
- If your app macro has defined one or more categories: select one category for your app,
- If your app macro has not defined a category: your macro will appear in the “Marketplace app macros” category and in search results
We’re eager to hear your thoughts:
- What are your thoughts on the slash command menu designs and the right rail component?
- What is your perspective on the new categories of elements?
- Are there any other potential challenges / opportunities you anticipate?
Your insights will help us refine the solution to better meet the needs of our shared users.
Rough Timelines
- Apr 2025: Phase 1 changes go live to the Live Docs Open Beta Cohort
- Jun 2025: Phase 2 changes & Interim category auto-remapping solution goes live to all customers
- Dec 2025: Final app category mappings confirmed and Vendors required to update app categories
Please let us know your thoughts in the discussion section. We appreciate your feedback and collaboration to make Confluence a better platform for all!
