• Products
  • Documentation
  • Resources

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
ConfluenceCloud_NewEditor_Toolbar
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 instance, 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.

  1. Click Preview page.  More detailed information is presented about the process.

  2. Click Convert page.  Page refreshes, and the content appears in the new editor.

  3. Click Publish… to save the new editor version of the page.

Enable auto-conversion in a space

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

  1. Go to the space in Confluence Cloud.

  2. Select Space settingsfrom the sidebar.

  3. Select Convert pages from the Manage space card.

  4. Toggle Convert pages automatically to the on position.

 

View of auto-convert editor function

Enable auto-conversion across Confluence

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

  1. Select the wheel icon () in the top-right corner to open Confluence administration.

  2. Find Settings > Configuration in the left-hand navigation.

  3. Select Further configuration.

  4. Select Edit from the top-right corner.

  5. Find Convert pages automatically and check Enable.

  6. Select Save.

auto-covert to new editor in further configuration within Confluence settings

 

If auto-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 auto-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

 

Additional Help