How we roll out the new editor in Confluence

Hello community,

Avinoam here from Confluence Cloud product management - I work on the new editor in Confluence. The rollout of the new editor is probably one of the biggest changes we’ve been rolling out gradually during the past year or so. This change impacts our customers deeply as one of the main tasks in Confluence is content creation, with the editor being at the heart of it.

We’ve learned a lot over the past year - what’s worked, what hasn’t worked. And thanks to all of your incredible feedback, we are finding ways to improve and to make the transition from the legacy editor to the new one a smoother and more valuable experience for you both as admins and as end users of the product.

One of the biggest pieces of feedback we’ve gotten is to increase the transparency into:

  1. Our roadmap

  2. Rollout process

  3. Plans for migrating content in the future

I’ll do my absolute best to follow one of Atlassian’s company value’s of Open Company, No Bull***t and explain each of the above areas in as much detail and transparency as possible.


We decided to open our roadmap and connect it to public facing tickets for as much transparency and ease of tracking as possible. It contains an exhaustive list of all features in the new editor compared to the legacy editor; it includes our future plans and links to the relevant public tickets for you to jump in on and watch for full visibility. If something seems off, the best way to impact the roadmap is to comment, vote, and watch the public facing tickets as they are a great source of feedback that we use to evaluate priorities over time. For example, these tickets are what helped us prioritize adding back full width and all the layout options into the new editor.

Your opinion matters, and we hear you. Even if we aren’t able to comment and respond to everything, we track all feedback and take it to heart, so please don’t take our silence as not listening or caring.

We opened this roadmap up publically a bit earlier than actually felt comfortable for us, but that was intentional since we preferred to start learning from you and getting valuable feedback sooner rather than later. If you find something is missing or is inaccurate, please comment on one of the tickets or on this community post. The roadmap is a living document, and we’ll update it based on your feedback weekly.

Rollout process

We rollout very gradually to specific groups of customers based on their usage patterns, size, type of content created, and many other factors - in a process designed to accelerate learning while minimizing the surface area so that we can respond to feedback as quickly and effectively as possible.

For each group of customers we rollout the editor to, there is roughly a 6-8 weeks rollout process from phases 1 → 3, and this is how we sequence the rollout process at a high level:


Rollout Phase 1 - Try out the new editor

  • In this phase, all new pages are still created in the legacy editor.

  • Only Blogs, Meeting Notes, and a blank page template are created in the new editor.

  • Existing pages still get edited in the legacy editor.

  • We put primary focus on the new editor template so that you can try it out and get used to it.


What actually happens in this phase:

image (62).png


Once users land in the new editor for the first time, they’ll also get onboarding (which actually has animated gifs) for the new editor right inside it.



Rollout Phase 2 - The new editor becomes the default for new pages

  • In this phase, all new pages are created in the new editor.

  • There is still a blank template to use the legacy editor.

  • Existing pages still get edited in the legacy editor.

image (61).png

What actually happens in this phase:

image (63).png

Rollout Phase 3 - The legacy editor is removed from new page creation

  • In this phase all new pages are created only in the new editor.

  • The blank template to use the legacy editor is no longer available*.

  • Existing pages still get edited in the legacy editor.

*This phase doesn’t include additional communications via email or in-product.


Migrations Phase 1 - Users can start to migrate their existing pages*

*As of November 2019 this capability is still in development and will soon start to get rolled out to customers and will also gradually become available to all customers.

We’ve built a self service page level opt in tool for users to be able to migrate their pages from the legacy editor to the new editor so they can do it gradually, at their pace, and when they’re ready. We’re starting from the page level as it will help is learn faster and continually improve the content migration process while minimizing the surface area.

The page level migration experience will look something like this at a high level:

page migrations 1.pngpage migrations 2.pngpage migrations 3.pngpage migrations 4.png

All migrations logic will be added in a very exhaustive manner to the same public facing roadmap once we start rolling out page level migrations.


Migrations Phase 2 - Admins can start to migrate their existing spaces*

*As of November 2019 this capability is still in development and isn’t planned to rollout to customers for a few more months.

In the spirit of sharing very openly and early, these are initial designs at a high level of how the space level bulk migrations will work:

space 1.pngspace 2.pngspace 3.pngspace 4.pngspace 5.png


Will the legacy editor eventually go away?

Yes. However, the legacy editor will likely still be around for a bit as we understand that existing content needs to keep working. With that being said, eventually, we do plan on moving away from the legacy editor. We’re actively working as we rollout to understand what the eventual sunsetting process will look like and we’ll be asking you for how you think it should work so we can make it as smooth as an experience as possible, with ample communications and change management supporting material.


We sincerely hope that this post helps to better inform everyone of what the rollout process looks like.

Please reach out with any feedback so we can constantly continue improving the rollout experience!




Davin Studer
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
October 22, 2019

"Existing pages still get created in the legacy editor."

Heads up, the above statement in phase two doesn't make sense. Existing pages don't get created ... they already exist.

There is a similar statement in phase 3.

Like # people like this
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
October 22, 2019

Ah good catch @Davin Studer - thanks for calling out! I'll fix those up.

Like # people like this
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
October 22, 2019

Done! thanks again, and please call out anything else :)

Like Mandy Ross likes this
Arthur Mack
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
October 23, 2019

Good to know we can have some control over our page migrations.



Like # people like this
Maurice Pasman October 24, 2019

@Avinoam thanks for the update, great to hear.

When I was first confronted with the new editor (I believe it was early February) it was just converting existing pages upon the first edit (messing up everything in the progress). This sure looks like a big improvement.

While the new editor is not yet perfect, I believe this will be a much less painful approach.

I especially like the option to preview the conversion, so when things don't work out, a support ticket can be raised and the conversion can be postponed until they are fixed.

Like # people like this
Todd Thomas October 28, 2019

This is great to see additional transparency with development. I applaud this group as setting a great tone and pace for other teams at Atlassian!

Will similar levels of transparency be given to other product areas within the Atlassian ecosystem? For example, Confluence Server or Jira Service Desk Server?

One of the challenges today is that even with the EAP system there isn't often a sense of what features will land per release cycle or when/if a long-awaited feature will be added to as a feature of a future release. Knowing when/if a particular feature will be released is critical to our team's ability to provide a solution to those we support with these applications. For example, if I know that feature X will be released in about 5 months from now, I may be able to wait. If there is nothing on the horizon coming from Atlassian, I will have to look at an alternative solution (or possibly different vendor).

Like # people like this
Kelvin A Hill October 29, 2019

Hi again, @Avinoam. Thanks for chatting yesterday.

I've taken a look at the migration plan, and I can confirm that it looks alarming.

Converting simple pages of text and graphics is a no brainer; so knock yourself out, as they say. But what about all those umpteen thousands of pages that cannot be automatically migrated without wholesale destruction of the content? Will customers be required to spend countless hours copying and pasting content at their own expense using a restrictive, functionally deficient set of macros simply because Atlassian has changed its strategy? I see lawsuits coming down the line.

The bulk-conversion process sounds like a recipe for disaster, too.

In our particular case, we have many hundreds of pages with content in customized DIVs, PANELs, SECTIONs, COLUMNs, and more besides. It will be fascinating to see what the automated-migration process makes of them. I suspect all that will be left after the conversion process will be the page title. To whom should we send the bill for having to manually copy/paste content from the current editor to one that has several important features stripped out?

Here's a real-world outline of one of our pages. I have indicated the macros in use. I have also incorporated a forward slash to show the close of each container macro:

[PANEL – customized using its border and background fields]

     [COLUMN – customized using its width field]


          IMAGE – with precise pixel width set

          [DIV – customized using its CSS Style field]

               TEXT – hyperlinked




          [TIP – with icon suppressed]


          [PAGE TREE]




I expect the migration script won't handle such a page in an elegant way, and we are highly unlikely to be impressed with whatever is left of the page.

By way of another example, in hundreds of pages that we export to customized, branded PDFs to be sent to our customers, 100% of the headings are contained in DIV macros—each with its own class and CSS settings to apply our own chosen sizing and override the built-in headings demotion (during PDF export). I wonder if the automatic-migration process will simply delete all our headings—thousands of them.

Like # people like this
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
October 29, 2019

@Kelvin A Hill thanks for the great feedback! This is why our rollout approach for migrations is to start with allowing customers to choose which individual pages they want migrated so we can learn from the feedback on what's working and what's not so we can keep improving until we're ready for a bulk (space) level migration. Full on later migrations are something we're actively looking into and examining several different approaches of how this could sequence or how the logic would work. In an ideal world, from your perspective - how would you imagine the migration process working in a way that's optimal for your needs?

David Gregory October 29, 2019

This looks like a significant improvement in both process and transparency (not perfect, but much better).

I am wondering how we might have errors provided to us if they were to occur during the migration process. This would be especially important if we do wholesale space-level migrations.

The ability to migrate a page tree (instead of an entire space) would be handy too.

Also, a query indicating which pages are in the old format would be truly useful to make sure that we haven't missed anything.

Kelvin A Hill October 30, 2019


Like Maurice Pasman likes this
Maurice Pasman October 30, 2019

Yeah. If only this was all a bad dream 😒

Like Kelvin A Hill likes this
Kelvin A Hill October 30, 2019

@Avinoam This is probably a good time to point out something else that Atlassian has probably overlooked. Consider the screenshot below. Some of our pages are regularly updated, and we use the page history to check what has been changed and by whom. Occasionally, we have no choice but to roll back to an earlier version.

Unfortunately, the moment we copy/paste content from the old editor into a new page, it's a case of...BOOM!...and our page history is gone. That's unacceptable.

Pray tell, will the automated-migration process also ditch the page history? And if by some miracle it preserves the page history, will it also retain the original page until a full manual comparison of the old and new content can be completed?page-versions.png

Like Christopher Koller likes this
Jeff Scattini November 11, 2019

Most of my pages follow along similar lines as @Kelvin A Hill has described. We have heavily relied on DIV, Column, and Anchor macros to define useful areas of content and link to important content that is not a heading. 

For example, in long lists of FAQs, we have a "back to top" link that connects to an Anchor at the top of the page so that our users don't have to scroll long distances. 

This page history issue is also concerning as I can't see how we could possibly move forward without being able to revisit the last ~20 edits to a page at will.

I am very uneasy about allowing my users access to the new editor when they could very easily wreck entire page trees of content without meaning to. And that's IF I was willing to ignore the pain of inconsistent user experiences trying to navigate old and new editors at the same or inconsistent wiki appearances.

Manually updating each page for just Anchor and Div macros would be a full time job for at least six months at my company, and that is assuming no one write a single new word in that time. 

@Avinoam  I am very glad that you will not be removing access to the old editor at this time. I'm honestly not sure how to design templates or architect my information to attempt to create pages without needed functionality but that can be converted easily into the new editor. All solutions I've come up with are, so far, so limited that they would drive users off of Confluence and back on to Gdrive. If your team has documented migration use cases beyond plain text and images that you can share, I'd appreciate a look at them. 

Kelvin A Hill November 12, 2019

@Maurice Pasman On October 24th, you wrote "While the new editor is not yet perfect..."

That was extremely gracious of you. Really generous.

I'd go further to say that the new elements work acceptably well, but only when they are deployed in the limited ways tested by the developers. If you wish to achieve a result that ventures beyond the basic editor inflexibility, however, you're in for a frustrating and disappointing experience. It's like the product was assembled in a vacuum—or tested by children.

There are simply too many bugs and omissions to assess the editor as anything more than a work in progress. It's scarcely more than a "nice to have" alternative for basic content. It is hopelessly unfit as a wholesale replacement for the current editor. And Atlassian is rolling it out while pretending it's a good thing. Perhaps they're about to say, "LOL, fooled you. It's an early beta. Thank you for doing our testing for us."

The new editor feels like it was built by a small group of developers with a limited checklist of functionality they wanted to introduce—while conveniently skipping over the ways many existing clients are working. I simply refuse to believe that anything more than scant user feedback was considered. It's like they've had their fingers in their ears while shouting, "La, la, la! We're not listening."

Like # people like this
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
November 12, 2019

@Jeff Scattini we're going to add a very detailed table for how the conversion of every element will work (this list will update over time as we add support for more elements of course) to the bottom of this page in the coming weeks once we start gradually rolling out the page opt in migrations capability, so stay tuned.

Jeff Scattini November 12, 2019

@Avinoam Thanks for the response, I appreciate it.

I'm very happy to wait for the conversion table until your team is ready to release it. I'll hold off planning my migration until the table is released. 

Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
November 12, 2019

@Jeff Scattini thanks to your inspiration, we're going to work on publishing that part sooner (before we even start rolling out page level migrations) so you and others can start looking at it and so we can start learning from you sooner. Please watch this page and we'll make sure to publish a notification on the change once we add it so you'll know when it's available.

Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
November 12, 2019
Like # people like this
Jeff Scattini November 15, 2019

Thanks, @Avinoam , This will be useful moving forward. 

I still don't want to make any conversion to the new editor until several other issues are resolved (Anchor macro/linking in general for example) but this table will definitely be useful when that conversion needs to happen. 

Julian Governale
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
November 21, 2019

@Avinoam One aspect im unsure of and may have just missed it, but when a page can not be converted due to one reason or another we then need to recreate the page in the new editor?  Or will all pages be converted and the elements that are not able to be migrated will just break? 

Kelvin A Hill November 21, 2019

@Julian Governale Excellent questions. I have raised similar concerns and am still waiting answers.

Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
November 22, 2019

@Julian Governale that's a great question! We'll be rolling out the page migration tool gradually first to sites we know have content we can migrate over, while in parallel we're working to have a migration path for all content - even if it's unsupported in the new editor, so that you still have it in a usable state once you migrate it. As we support more content we'll rollout migration tooling further. Once we start rolling out we'll make sure to share exactly how the tooling will work in detail, which will be soon. In the meantime, we added a very detailed element conversion table of all content here:

David King November 22, 2019

@Avinoam  Thank you for the update. The migration plan will help us make some decisions in the near term.

Our company was recently placed in Rollout Phase 2, and we have instructed users not to use the new editor. It simply has too many issues, and users are unhappy as a result. While much of our user base are light users, the power users are highly frustrated. One problem is that occasionally users forget and still use the new editor. We have some new content we need to recreate as a result.

We have also opened a ticket to have our account rolled back to Phase 1, in order to make it easier for users to not inadvertently create new pages with the new editor. I doubt that the request will be honored, because it looks as though we are all getting the new editor as our only choice whether we want it or not.

Given the state of the new editor, if we are moved to Phase 3, which according to the rough timeline you lay out might be in two to three weeks, we will freeze all new content creation and begin moving content elsewhere.

The problem with your migration plan and the "opening up" of the roadmap is that flaws in the new editor play no part in the roll-out. The only thing we can do is "vote" on features that were arbitrarily removed or have serious bugs, while you take away the legacy editor that works. Atlassian is putting the proverbial cart before the horse: the normal course is to fix bugs, put in required features and then roll out. Your scheme is to force a roll-out on users, then have them vote on which bugs they want fixed first. Or to use another analogy, it's like a surgeon telling a healthy patient that all their limbs will be amputated, but that they can indicate which ones they feel are more important to be re-attached.

I don't doubt this project started with good intentions, but in the face of hundreds of negative comments from the community and many more in open tickets, I cannot understand why the roll-out and migration continue. I appreciate your engagement with the community, but have grave concerns whether your organization has listened to its customers.

Like # people like this
Tom Crowley November 24, 2019

@Avinoam, a few brief points:

  • Until you know exactly how old pages with incompatible macros are going to migrate to new pages, you shouldn't even start talking about sunsetting the legacy editor. It becomes more and more clear with each communication that no one had thought this process through to the end or questioned how it would affect users. 
  • This article was published on the 22nd of October. Way too late. By this point we were already on the new editor. We joined Confluence mid-flux, and foolishly thought that because you were rolling it out, it was ready for use. We migrated the site over to use the new editor so that our users didn't have to learn two different interfaces.
    We had some resistance trying to get people to migrate their stuff onto Confluence, so I didn't want to ask them to get familiar with one editor knowing that it was being killed off. If I'd know how long it was going to take, and how bad it was, I would have taken the hit there, and avoided taking the hit with user complaints about functionality.
  • If this article was published on the 22nd of October, how have I only seen it now? And only because @Bob Sovers linked it on a discussion I started because Atlassian closed the one previously being used? So when we say you aren't listening and are ignoring us, it could theoretically be the case that you are just typing away somewhere else without telling us.
  • In the spirit of this, someone mentions in passing on a Jira ticket that "According to a web presentation held by Avinoam last week, Atlassian also offers to defer the new "experience" until February, 1st." I've not seen the invite for this, the presentation, or the offer of deferral. I've been fairly active on the community, as you probably know, so I'm not sure how these things managed to pass me by, but apparently they did. You need to be more proactively open. Too many of us are learning about things second-hand from other community members. It shouldn't work like that.
  • The more this farce goes on, the more evident it is that unless doing so would literally bankrupt the company, you cannot justify not running both legacy and fabric editors side by side indefinitely. Give customers the option to use the one that meets their needs. Offer to revert or migrate-back any customers on the new editor. You can't start moving people into Phase 2 until a lot of things are fixed, and my guess is that we're a couple of years away from that.

I keep thinking I've said all I should say on here. I've written short angry comments, I've posted carefully thought out essays. I've emailed the CEOs. I've tried to help other people use the editor or find information about it. In sum, I've wasted a hell of a lot of time. My tune isn't going to change, so I should just walk away and suffer in silence until we can find a way of getting rid of Confluence in our business. But you just keep doing things that don't make sense. You keep finding new ways to tempt me back here to see if everyone else is as confused and angry as I am about the latest example of poor project/product/change management.

So... Until next time...

Like # people like this
Bec Honey November 26, 2019

Nice road map and pretty images... But, where's the explanation for WHY? 

What was the thought process behind doing a new editor? Where there too many complaints / tickets assigned to the old one? 

Is this a job creating exercise for the editor development team? ...Were you all a bit bored? 

Atlassian:  Let's release a new version of editor... Let's let them know they can comment on what they like/ don't like about the new editor. 

User's : Its pretty Bad. Please don't swap it over to this. It'll wreak our existing confluence content and adding more content will be out of whack and look silly. Thanks. 

Atlassian: Let's Keep going.... let  them know the old version is going away soon. Get them to tell us what functionality they really want for the new editor.

User's :  OK, We'll keep testing it for you, so you know what to fix,  you raise tickets based on our testing, and we'll get annoyed and post on the discussion boards to make ourselves feel a little better/ find work arounds to the problems we are encountering. 

Atlassian:  Ok folks, hold on tight!... Take away what they were using (the old editor). Force them to use the new editor! (Even though we haven't completed our list of 'to -do's' from their feedback *testing

User's : Multiple angry threads. More testing. More tickets for you to work on. 


I must say... Kudos guys!...  

a) You've got plenty to work on. 

b) Got all this testing for free.


*By "free" I mean, our employers are paying you for a product and paying us for the time its taking us to find bugs and report them to you. 


Like # people like this


Log in or Sign up to comment
AUG Leaders

Atlassian Community Events