Convert pages to the new editor

When the page conversion functionality is available in your Confluence instance, you can:

choose which pages get converted to the new editor functionality and when.
preview any page before converting it.
restore a page to its previous, legacy editor version.

Which editor does your page use?

You can see which editor your page uses by looking at the differences in the editor toolbar.

The New editor: Includes Publish… or Update and Close buttons in the top menu and the emoji icon
The Legacy editor: Has earlier versions of text-color picker and page formatting

New editor

Legacy editor

Image highlights the unique tools that make the toolbar in the legacy editor different than the one in the new editor

Page conversion

When page conversion is turned on for your site, you'll get a banner notification at the top of the first page you edit, and you’ll see a notification at the lower left of the page.

Pages that can be converted from the legacy to new editor display a notification.

Convert a page

Before clicking convert, we want to give you a chance to see how the page will look in the new editing experience.

Click Preview page. More detailed information is presented about the process.
Click Convert page. Page refreshes, and the content appears in the new editor.
Click Publish… to save the new editor version of the page.

Enable Space-Level Auto-conversion

Space admins can enable auto-conversion from legacy to the new editor for all pages with eligible content in a space. To do this:

Navigate to Space Settings → Manage Space → Convert Pages
Toggle on Convert pages automatically setting

Enable Site-Level Auto-conversion

Site admins can enable auto-conversion from legacy to the new editor for all pages containing eligible content within a site.

Navigate to Site Settings → Further Configuration → Convert pages automatically
Check Enable

auto-covert to new editor in further configuration within settings

If space or site conversion is enabled, eligible pages will be previewed in the new editor until published, at which point the new editor is “saved.” This can be reverted to legacy in page history.

If space or site conversion is not enabled, only pages that were published in the new editor will stay in the new editor.

What actually happens when your content is converted?

We want you to trust that we are handling your information properly. This table details all the elements that you can add to a legacy editor page in all their complex combinations. You can easily scan to find out which elements are available in which editor and what happens when a page containing that element is converted to the new editor. Most elements convert completely. However, for those which are modified slightly, you’ll find the details of what happens. If an element can’t be converted, you’ll find information about our short-term or long-term plans as well as Confluence Cloud Support requests if we are already tracking it. Keep in mind that this information will change as we refine the conversion rules and resolve the elements that can't be converted yet.

The following terms are used in the details of this page:

Rich body macro is a container in which the page creator/editor can type text or insert page elements. Examples of rich body macros in the legacy editor include the Note macro, Chart macro, Page Properties macro, and the Table of Content Zone macro.
Block macro is a static element that pulls content into the page based on properties set in the macro, and it doesn’t allow the page creator/editor to type inside the macro. Examples of a block macro in the legacy editor include the Questions List macro or the Related Labels macro.

Legacy editor elements	Category	In legacy editor	In new editor	What happens when converted?
@ mention	Reference			Converts completely
Align macro	Macro			Converts completely Even though this macro was removed from the new editor and replaced with toolbar actions, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor. The content in the body of the macro can be edited.
Anchor macro	Macro			Converts completely
Attachments macro	Macro			Converts completely
Attachments to the page	Reference			Converts completely
Background color macro	Macro			Can’t convert (reference CONFCLOUD-68492) The text inside the macro is brought over to the converted page, but the background color is removed.
Basic table	Structure			Converts completely
Blog posts macro	Macro			Converts completely
Bold text	Text style			Converts completely
Center macro	Macro		Action exists in toolbar	Converts completely Even though this macro was removed from the new editor and replaced with toolbar actions, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor. The content in the body of the macro can be edited.
Change-history macro	Macro			Converts completely
Chart macro	Macro			Converts completely
Cheese macro	Macro			Converts completely Even though this macro was removed from the new editor, the conversion removes the macro and replaces it with the text, "I like cheese".
Children display macro	Macro			Converts completely
Code block macro	Macro		Element exists in slash command	Converts with modification This macro was removed from the new editor and replaced with the Code Snippet element (type /code). Conversion removes the Code Block macro, moves the text into a Code snippet element, and allows you to choose the appropriate language.
Column (single)	Presentation			Converts with modification (reference CONFCLOUD-67198) The single-column layout option was removed in the new editor. Conversion removes the single column and makes all the content within fixed-width.
Column macro	Macro		Action exists in toolbar	Converts completely The macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor. The content in the body of the macro can be edited. New layouts can be created in the new editor using the Layouts tool in the toolbar.
Columns (three, even)	Presentation			Converts completely
Columns (three, even, with side bars)	Presentation			Converts completely
Columns (two, even)	Presentation			Converts completely
Columns (two, with left side bar)	Presentation			Converts completely
Columns (two, with right side bar)	Presentation			Converts completely
Comment (inline)	Page interaction			Converts completely
Comment (inline on an image)	Page interaction			Can’t convert (reference CONFCLOUD-67745) There is no way to show the comment in the new editor, yet.
Comment (page level)	Page interaction			Converts completely
Comment (resolved)	Page interaction			Converts completely
Confluence data-driven roadmap macro	Macro			Converts completely
Content by label macro	Macro			Converts completely
Content by user macro	Macro			Converts completely (reference CONFCLOUD-33832) The macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor.
Content report table macro	Macro			Converts completely
Contributors macro	Macro			Converts completely
Contributors summary macro	Macro			Converts completely
Copyright macro	Macro			Converts completely (reference CONFCLOUD-68495) The macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor. The content in the body of the macro can be edited.
Create from template macro	Macro			Converts completely
Create space button macro	Macro			Converts completely (reference CONFCLOUD-68494) The macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor.
Div macro	Macro			Converts completely (reference CONFCLOUD-65774) The macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor. The content in the body of the macro can be edited.
Emoticons	Media			Converts completely
Excerpt include macro	Macro			Converts completely
Excerpt macro	Macro			Converts completely
Expand macro	Macro			Converts completely The macro is replaced by the new element. Your heading and content are unchanged.
Fancy bullets macro	Macro			Converts completely (reference CONFCLOUD-68496) The macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor. The content in the body of the macro can be edited.
Favorite pages macro	Macro			Converts completely (reference CONFCLOUD-68497) The macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor.
File from another page	Reference			Converts completely
File shown as link	Navigation			Converts completely
File shown as thumbnail	Presentation			Converts completely (reference CONFCLOUD-67512) Conversion is completed after a page refresh is performed.
Gallery macro	Macro			Converts completely
Giffy diagram macro	Macro			Converts completely
Global reports macro	Macro			Converts completely (reference CONFCLOUD-68498) The macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor.
Google Drive macros	Macro			Converts completely
Heading 1 text style	Text style			Converts completely
Heading 2 text style	Text style			Converts completely
Heading 3 text style	Text style			Converts completely
Heading 4 text style	Text style			Converts completely
Heading 5 text style	Text style			Converts completely
Heading 6 text style	Text style			Converts completely
Headings 1 through 6 applied to an item in a list	Text style			Converts with modification (reference CONFCLOUD-68499) Doesn't preserve the formatting from the legacy editor, but a new formatting scheme is applied to visually differentiate between the levels: - HEADING ONE (all caps and bold) - Heading Two (bold and italic) - Heading Three (bold) - Heading Four (grey and bold) - Heading Five (grey and italic) - Heading Six (grey)
Highlight macro	Macro			Converts completely (reference CONFCLOUD-68517) Even though this macro was removed from the new editor, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor. The content in the body of the macro can be edited.
Horizontal rule	Presentation			Converts completely
Horizontal rule in a list	Presentation			Converts with modification Horizontal rule is given its own line below the list.
Horizontal rule in a macro	Presentation			Converts completely
Horizontal rule in a table	Presentation			Converts completely
HTML comment macro	Macro			Converts completely (reference CONFCLOUD-65854) Even though this macro was removed from the new editor, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor. The content in the body of the macro can be edited.
iFrame macro	Macro			Converts completely
IM presence macro	Macro			Converts completely (reference CONFCLOUD-68500) Even though this macro was removed from the new editor, the output of the macro is carried over to the new editor. The settings can’t be changed in the new editor.
Image as a list item (on its own line)	Presentation			Converts completely Image is maintained as a list item.
Image inline in a list	Presentation			Converts with modification (reference CONFCLOUD-67862) Line breaks are added before and after the image placing the image on its own line. Images can't be placed in a sentence in the new editor.
Image inserted into a sentence	Presentation		custom emoji workaround	Converts with modification (reference CONFCLOUD-68501) Line breaks are added before and after the image placing the image on its own line. Images can't be placed in a sentence in the new editor; however, you can create a custom emoji for icons or other small images to be inserted into the flow of a sentence.
Image inserted into a table	Presentation			Converts with modification (reference CONFCLOUD-66401) The image converts, but the spacing and sizing of the image may differ.
Image inserted on it own line	Presentation			Converts with modification The image converts, but the spacing and sizing of the image may differ.
Image with a border	Presentation			Converts with modification (reference CONFCLOUD-67122) Borders are removed. Borders can be applied using the new editor's image annotation feature.
Image with a link	Presentation			Converts completely After conversion, the link can’t be modified in the new editor.
Image with a specific pixel size	Presentation			Converts with modification (reference CONFCLOUD-67554) Images in the new editor align to a grid. The grid size closest to the pixel size is applied, and the image is centered on the page.
Image with Alt text	Presentation			Converts completely
Image with an effect	Presentation			Can’t convert (reference CONFCLOUD-67122) Effects are removed and can't be reapplied.
Image with title text	Presentation			Can’t convert (reference CONFCLOUD-67122) Title text is removed and can't be reapplied.
Include page macro	Macro			Converts completely
Info macro	Macro			Converts completely
Italic text	Text style			Converts completely
Jira chart	Macro			Converts completely
Jira chart macro	Macro			Converts completely
Jira filter	Macro			Converts completely
Jira issue	Macro			Converts completely
Jira issues calendar macro	Macro			Converts completely
Jira issues macro	Macro			Converts completely
Jira macro	Macro			Converts completely
Jira roadmap macro	Macro			Converts completely
JUnit report macro	Macro			Converts completely (reference CONFCLOUD-65317) Even though this macro was removed from the new editor, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor.
Labels list macro	Macro			Converts completely
Links to anchors	Navigation			Converts completely (reference CONFCLOUD-66773) When converted, the link to the anchor location still works but the Anchor macro is invisible.
Links to attachments	Navigation			Can’t convert (reference CONFCLOUD-65302)
Links to external pages	Navigation			Converts completely
Links to headings on a different page	Navigation			Can’t convert The link navigates you to the page but not to the heading specified.
Links to headings on the same page	Navigation			Can’t convert The text is maintained, but the link to the heading is broken.
Links to other pages	Navigation			Converts completely
List with an image	Structure			Converts completely
List with bullets and numbers	Structure			Converts completely
Lists, bulleted (created with the Fancy bullets macro)	Structure			Converts completely Even though this macro was removed from the new editor and replaced with toolbar actions, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor. The content in the body of the macro can be edited.
Lists, bulleted (more than 6 levels)	Structure			Converts with modification The new editor only allows lists with 6 levels, so the conversion of levels 1 through 6 are handled without issue. Levels 7 and deeper are outdented to level 6.
Lists, bulleted (nothing inserted, no numbered sections)	Structure			Converts completely
Lists, numbered (more than 6 levels)	Structure			Converts completely The new editor only allows lists with 6 levels, so the conversion of levels 1 through 6 are handled without issue. Levels 7 and deeper are outdented to level 6.
Lists, numbered (nothing inserted, no bulleted sections)	Structure			Converts completely
Livesearch macro	Macro			Converts completely
Loremipsum macro	Macro			Converts completely (reference CONFCLOUD-68502) Even though this macro was removed from the new editor, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor.
Macro in a table	Nested elements			Can’t convert (reference CONFCLOUD-63350)
Macro in a task	Nested elements			Converts with modification Tasks with certain macros can be converted, like the Jira Issue macro; however, others can't like the Children Display macro.
Macro, rich body macro that contains a block macro	Nested elements			Converts completely
Macro, rich body macro that contains another rich body macro	Nested elements			Can’t convert (reference CONFCLOUD-66888)
Macro inside a list	Macro			Can’t convert (reference CONFCLOUD-67862)
Monospace text	Text style		accomplished with the Code Snippet element	Converts with modification Converts the text as monospace and retains whatever text color was applied. However, a grey background is applied to the text.
Multimedia macro	Macro			Converts completely Even though this macro was removed from the new editor, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor.
Navigation map macro	Macro			Converts completely Even though this macro was removed from the new editor, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor.
Network macro	Macro			Converts completely Even though this macro was removed from the new editor, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor.
Noformat macro	Macro			Converts with modification (reference CONFCLOUD-68503) This macro was removed from the new editor and replaced with the Code Snippet element (type /code). Conversion removes the Noformat macro, moves the text into a Code Snippet element, and allows you to choose the appropriate language.
Note macro	Macro		accomplished with the Info Panel element	Converts with modification Conversion removes the specific, unitasking macro, replaces it with the Info Panel element, and assigns the appropriate background color and icon; there is no option in the new element to remove the icon.
Office Excel macro	Macro			Converts completely
Office PowerPoint macro	Macro			Converts completely
Office Word macro	Macro			Converts completely
Page index macro	Macro			Converts completely
Page properties macro	Macro			Converts completely
Page properties report macro	Macro			Converts completely
Page tree macro	Macro			Converts completely
Page tree search macro	Macro			Converts completely
Panel macro	Macro			Converts completely (reference CONFCLOUD-66752) The macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor. The content in the body of the macro can be edited. Paragraph styles applied to text in the panel are maintained.
Panel macro containing another macro	Macro			Converts completely (reference CONFCLOUD-66888) The macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor. The content in the body of the macro can be edited. Paragraph styles applied to text in the panel are maintained.
Panel macro with text formatted as a heading	Macro			Converts completely (reference CONFCLOUD-66752) The macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor. The content in the body of the macro can be edited. Paragraph styles applied to text in the panel are maintained.
Panel macro with text formatted with the Preformatted style	Macro			Converts completely (reference CONFCLOUD-66752) The macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor. The Preformatted paragraph style remains as it was in the legacy editor.
Panel macro with text formatted with the Quote style	Macro			Converts completely (reference CONFCLOUD-66752) The macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor. The content in the body of the macro can be edited. Paragraph styles applied to text in the panel are maintained.
Paragraph text style at fixed-width	Text style			Converts completely
PDF macro	Macro			Converts completely
Popular labels macro	Macro			Converts completely
Preformatted text style	Text style			Converts with modification (reference CONFCLOUD-59714) This paragraph style is modified during conversion. The formatting will be changed to superscript.
Privacy mark macro	Macro			Converts completely (reference CONFCLOUD-68504) Even though this macro was removed from the new editor, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor.
Privacy policy macro	Macro			Converts completely Even though this macro was removed from the new editor, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor. The content in the body of the macro can be edited.
Profile picture macro	Macro			Converts completely
Questions list macro	Macro			Converts completely
Quote formatted text style	Text style			Converts completely
Recently updated dashboard macro	Macro			Converts completely
Recently updated macro	Macro			Converts completely
Recently used labels macro	Macro			Converts completely (reference CONFCLOUD-68506) Even though this macro was removed from the new editor, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor.
Registered trademark macro	Macro			Converts completely (reference CONFCLOUD-68507) Even though this macro was removed from the new editor, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor.
Related labels macro	Macro			Converts completely
Retrospective button macro	Macro			Converts completely
Roadmap planner macro	Macro			Converts completely
Search results macro	Macro			Converts completely (reference CONFCLOUD-67827) Even though this macro was removed from the new editor, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor.
Section macro	Macro			Converts completely (reference CONFCLOUD-68508) Even though this macro was removed from the new editor, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor. The content in the body of the macro can be edited.
Service mark macro	Macro			Converts completely (reference CONFCLOUD-68509) Even though this macro was removed from the new editor, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor.
Shared links bookmarklet button macro	Macro			Converts completely (reference CONFCLOUD-68510) Even though this macro was removed from the new editor, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor.
Space attachments macro	Macro			Converts completely (reference CONFCLOUD-60005) Even though this macro was removed from the new editor, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor.
Space details macro	Macro			Converts completely (reference CONFCLOUD-68511) Even though this macro was removed from the new editor, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor.
Spaces list macro	Macro			Converts completely
Span macro	Macro			Converts completely (reference CONFCLOUD-65321) Even though this macro was removed from the new editor, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor. The content in the body of the macro can be edited.
Status macro	Macro			Converts completely The macro is replaced by the new element that is available from the insert menu or a slash command (type /status).
Status macro with outline style	Presentation			Converts with modification (reference CONFCLOUD-68512) Macro is converted to a new element, but the outline style is removed as it is not available in the new editor.
Strike macro	Macro		Action only exists in toolbar	Converts completely (reference CONFCLOUD-68514) The macro that used red sketchy lines is removed, and standard strikethrough formatting is applied to the text.
Strikethrough text	Text style			Converts completely
Style macro	Macro			Converts completely (reference CONFCLOUD-65321) The macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor. The content in the body of the macro can be edited.
Subscript text	Text style			Converts completely
Superscript text	Text style			Converts completely
Symbols	Presentation		rely on OS shortcuts	Converts completely (reference CONFCLOUD-67811) Even though symbols were removed from the new editor, symbols are converted without issue. To insert standard symbols into your content, consult the keyboard shortcuts available for your computer's operating system.
Table, basic	Presentation			Converts with modification The cell height of the converted table differs.
Table in a list	Presentation			Can’t convert (reference CONFCLOUD-58656) This could be accomplished in earlier versions of the legacy editor and can't be converted to the new editor.
Table in a table	Presentation			Can’t convert (reference CONFCLOUD-58656) This could be accomplished in earlier versions of the legacy editor and can't be converted to the new editor.
Table of content zone macro	Presentation			Converts completely
Table of content zone macro containing another macro	Presentation			Converts completely This works when block macros are inserted; rich body macros inserted into the TOC Zone macro can't be converted.
Table of contents macro	Presentation			Converts completely
Table that is fixed-width	Presentation			Converts with modification Converts the table, but the column and text won't be the same. The new editor offers fixed-width, wide width, and full-width.
Table that is responsive	Presentation			Converts with modification Converts the table, but the column and text won't be the same. The new editor offers fixed-width, wide width, and full-width.
Table with a heading column	Presentation			Converts completely
Table with a heading row	Presentation			Converts completely
Table with a numbering column	Presentation			Converts completely
Table with cells that have background colors	Presentation			Converts completely
Table with sortable headers	Presentation			Converts completely
Task list	Presentation			Converts completely
Task list containing a horizontal rule	Presentation			Can’t convert (reference CONFCLOUD-68515)
Task list containing an element	Presentation			Converts completely Elements include Code snippet, Date, Decision, Expand, Quote, Status
Task list containing a macro	Presentation			Can’t convert (reference CONFCLOUD-67862) Task lists containing the Jira issue macro converts without issue. Other macros, like Questions List and Children Display, can't convert.
Task list containing a table	Presentation			Can’t convert (reference CONFCLOUD-58656) Could be accomplished in earlier versions of the legacy editor, and can't be converted to the new editor.
Task list containing an image on its own line	Presentation			Converts completely
Task list containing any paragraph style (H1 through H6, Preformatted, Quote, Monospace)	Presentation			Can’t convert (reference CONFCLOUD-68499) The new editor does not allow these styles to be applied in task lists.
Task report macro	Macro			Converts completely
Team Calendar, add existing	Macro			Converts completely
Team Calendar, add new	Macro			Converts completely
Team Calendar, import calendar	Macro			Converts completely
Team Calendar, subscribe by URL	Macro			Converts completely
Text center, aligned	Presentation			Converts completely
Text, left-aligned	Presentation			Converts completely
Text, right-aligned	Presentation			Converts completely
Text with color applied	Text style			Converts completely The conversion preserves the color even if the color doesn't exist in the new editor; if you edit the color in the new editor, you can only select from the eight available colors.
Text with indents	Presentation	Toolbar	Keyboard	Converts completely (reference CONFCLOUD-67176) The toolbar controls for indent and outdent were removed in the new editor. Use Tab to indent and Shift + Tab to outdent.
Text with outdents	Presentation	Toolbar	Keyboard	Converts completely (reference CONFCLOUD-67176) The toolbar controls for indent and outdent were removed in the new editor. Use Tab to indent and Shift + Tab to outdent.
Tip macro	Macro		accomplished with the Info Panel element	Converts completely (reference CONFCLOUD-68516) Conversion removes the specific, unitasking macro, replaces it with the Info Panel element, and assigns the appropriate background color and icon; there is no option in the new element to remove the icon.
Trademark macro	Macro			Converts completely (reference CONFCLOUD-68507) Even though this macro was removed from the new editor, the macro and its settings are carried over to the new editor. The settings can’t be changed in the new editor.
Trello boards macro	Macro			Converts completely
Trello card macro	Macro			Converts completely
Underline text	Text style			Converts completely
User list macro	Macro			Converts completely
User profile macro	Macro			Converts completely
Warning macro	Macro		accomplished with the Info Panel element	Converts completely (reference CONFCLOUD-67577) Conversion removes the specific, unitasking macro, replaces it with the Info Panel element, and assigns the appropriate background color and icon; there is no option in the new element to remove the icon.
Widget connector macro	Macro			Converts completely (reference CONFCLOUD-67611) In the legacy editor, pasting a link to a video onto the page would automatically add this widget that would contain the video