Late last year we announced that A New Year will bring a new Confluence Cloud editor. This, as promised, is our follow up post in which we're going to cover additional details about how we're rolling this change out, and what it will mean for you.
Rollout approach
We're going to be rolling out the new editor to all eligible Confluence Cloud customers during the first quarter of this calendar year, starting in late Jan
- This means that all new pages they create will use the new editor, and any existing pages, when edited, will also be converted to the new editor.
'Eligible' means that in the last 90 days, no user or app on this instance has created content that we can't support or migrate. If a user or app has created content in the last 90 days that can't be migrated, that entire site will be temporarily excluded from the rollout. If a site has unsupported content older than 90 days, they will still get migrated, but those pages will continue to open in the old editor.
We'll be rolling out gradually, starting with the simplest, most dormant customers, and ending with the most complex and active.
For each cohort, there will be a 6 week sequence that starts with communications about the migration (to both admins and end users) and a trial of the new editor, and ends with the entire instance migrated to the new editor.
What this means for you
If you're a vendor offering macros for the existing Confluence editor, you'll need to ensure that your macros also work with the new editor. To do this, please follow the instructions below that correspond to your macro's body type.
All macros will continue to work in the old editor, both before and after you've made the following updates, although they may look and behave differently. We recommend testing updated macros in both editors to ensure that everything works as expected.
Bodiless macros
These are block or inline dynamic content macros with the following in atlassian-connect.json
"bodyType": "none"
In the new editor, these macros will now be WYSIWYG (what you see is what you get). This means that they will no longer use the macro placeholder image, but will look the same while editing as they do when published.
These macros should continue to work in the new editor, but you may need to update their sizing to accommodate the new width options. After updating the macro, you'll also need to verify that the updates have flowed through to the editor.
Update macros for sizing
The width of block level macros can be either block, wide, or full-width. This is controlled by the editor, so make sure that you haven't set any width values in atlassian-connect.json or in the CSS, as this may cause the macro to work incorrectly.
The height of the macro is controlled by the CSS macro height, which you can set and change dynamically as appropriate.
Update the macro in the editor
After editing a WYSIWYG macro in a custom macro editor, you need to update its parameters in order to trigger an update in the editor.
AP.require(["confluence"], function (confluence) {
confluence.saveMacro({
'param': version + 1
});
confluence.closeMacroEditor();
return true;
});
This can be done by storing a revision number in the parameters, or by updating any other parameter you might need to store within the macro.
Rich text bodied macros
These are block or inline dynamic content macros with the following in atlassian-connect.json
"bodyType": "rich-text"
These macros may continue to work as they are, or may require significant modification, as we'll cover below.
Deprecation of nested bodied macros
We'd announced the deprecation of nested bodied macros in our post Introducing live macros to support a new editing experience in Confluence Cloud. This will affect you differently based on whether your macro depends on nesting another bodied macro, or on the rich text functionality.
Macros that nest other bodied macros
An example of this is some of the macros in Confluence Server, which provide tabs by having a rich-text bodied container macro, with additional rich-text bodied container macros within it for each of the individual tabs.
The ability to nest bodied macros is no longer supported in the new editor. We know that this will be disruptive to existing vendors who have Cloud macros that rely on this functionality, but the overall usage across our customers in Cloud instances is very small. To help deal with this, we won't be rolling out the editor to any instances that have created new pages with nested bodied macros in the last 90 days, until we have a way to migrate those macros.
We recommend changing these macros to be WYSIWYG, and using the custom macro editor for any inputs or settings that can't be changed directly from the page. The new editor is part of https://atlaskit.atlassian.com/
Other rich-text macros
Macros that don't rely on nesting other bodied rich-text macros but which only utilize the container will continue to work in the new editor, with the caveat that other bodied macros cannot be nested inside them.
This means, for example, that you can no longer create an expand or page properties macro inside another bodied macro. Macros that don't have a body, like a Jira issue macro or task report macrocan still be nested inside bodied macros.
We are planning on converting the expand and page properties macros to native editor components so that, in the future, you will be able to nest them inside rich-text macros.
Converting existing bodied macros
This is not currently supported, but will be in the future. Watch this ticket to follow its progress and be notified when it’s complete.
CONFCLOUD-65437
To convert your existing macros to WYSIWYG macros, you need to change the body type of your dynamic content macro in atlassian-connect.json from:
"bodyType": "rich-text",
to:
"bodyType": "none",
Then, when someone requests a page that has the old bodied macro, we'll store the macro body in a content property.
You can request the existing content of the old bodied macro using the REST API. The content property will be stored under the page where the macro is contained using the macro key as an identifier.
https://{instance}.atlassian.net/wiki/rest/api/content/{contentId}/property/{macro-key}-macrobody
You'll still need to decide what to do with the storage format returned by the APIs, and how to present that in the new WYSIWYG macro.
There are APIs to convert the storage format to the view format, as well as to the Atlassian document format, which is the format used by the new atlaskit editor.
https://developer.atlassian.com/cloud/confluence/rest/#api-contentbody-convert-to-post
Testing
You can test these changes by doing either of the following:
- Create a new blog post: for 90% of users, the new editor has been turned on for all new blog posts.
- Request editor on your developer instance: Fill in this Google form to request us to enable the new editor on your developer instance for all new pages.
Still have questions?
We have answers! Head over to the Developer Community with your questions, concerns, or any other feedback, and we'll be happy to help you out.