Migrating from Confluence On-Premise (Data Center/Server) to Cloud: Differences in Macros, Editor, and Features

In our previous article, we discussed the technical aspects of migrating our app documentation from Confluence Data Center to Confluence Cloud, including a content review, clean-up, the migration process, and setting up redirections for existing Confluence links.

Having carried out the technical migration, our post-cloud migration checklist included:

• Removing our Enterprise Theme and other legacy macros.
• Converting migrated content from the legacy editor into the new Cloud editor.
• Exploring Confluence Cloud’s built-in features.

We delve into all of these steps in this article. We hope this will help you if you are considering migrating from Confluence On-Premise (Data Center/Server) to Cloud.

Steps to Follow Post-Confluence Cloud Migration

Step #1: Getting rid of Enterprise Theme macros

The content audit (refer to Part 1) identified the most relevant and migration-worthy pages. However, a major challenge arose: many pages used our Enterprise Theme app‘s elements (like macros, buttons, and tabs), which are unsupported in Confluence Cloud. This resulted in error messages on the migrated pages.

Rebuilding menus

We frequently used the “Enterprise Theme Box” macro in our Data Center documentation. This is a customized box with helpful links in the left sidebar.

In Confluence Cloud, we can insert similar links using Space Shortcuts. While it lacks some features like color selection, the impact of this on external visitors is minimal.

Replacing Tabs with Navitabs

We replaced the existing Enterprise Theme tabs with macros from our Navitabs app, which is available on Cloud. This also offered new possibilities, like embedding external content in tabs, which wasn’t available on Confluence On-Premise.

More changes

We replaced specific Enterprise Theme macros with standard macros offering similar functions, like built-in panels for general boxes. Thanks to our developers at bitvoodoo, existing custom panels from the Enterprise Theme are compatible with our Advanced Panelboxes cloud app. This allowed us to maintain a consistent documentation layout without adapting every single page.

Getting rid of Enterprise Theme macros sometimes required manual adjustments to the page content. Other macros could be replaced automatically with “search and replace” in all affected spaces (done by an admin in the code or with a 3rd-party app).

Please read our Migration Guide for Enterprise Theme for more details.

Step #2: Getting to know the Cloud editor

We were excited when we could finally view our migrated pages on Confluence Cloud.

Issues with the Legacy Cloud editor

😕 However, the initial appearance of the migrated pages in Confluence Cloud was underwhelming: text blocks were squeezed in, taking the entire page width. What had happened?

During the migration, the existing content was transferred to the Legacy Editor. This old editor essentially has the same features as the editor in Server or Data Center but changes the proportions of the page elements, leading to a poor layout.

💡 We wondered how to enhance the page layout for better appeal and readability. Fortunately, Atlassian provides a workflow for this.

Converting migrated Confluence content to the new Cloud editor

Upon editing a migrated page, a prominent banner appears in the header:

Clicking “Preview” allows viewing the page in the new Cloud Editor. Often, this enhances the page’s visual appeal compared to the Legacy Editor, and the page can be directly converted.

In other cases, there may be issues with Confluence macros:

• Macros are unavailable in Confluence Cloud
• Macros still exist but offer fewer functions than they did on Confluence Data Center.

Atlassian provides a helpful list of the differences in the editors. If issues arise, it’s better to leave the page in the Legacy Editor, thoroughly rebuild it, and then preview it again. In some cases, macros may need to be completely deleted. In others, you may be able to replace them with standard macros.

Again, creativity and courage are key. Replicating complex page content for the cloud often isn’t practical. For example, the nesting of several macros in the Confluence Cloud Editor is only possible to a very limited extent. While annoying, this restriction is also an opportunity to reduce pages’ complexity and split page content into multiple sub-pages.

For instance, the new Cloud editor can’t insert the “Expand” macro within a list. However, it is also often not strictly necessary; the content of the “Expand” macro could also be inserted directly into the list, bypassing the need for another macro. We chose this option and then published the page in the new editor. The result is a “fresher” look with all vital content seamlessly transferred.

Changing the page width

Reading habits evolve, and it can be difficult for users to read long texts stretched out in width, especially if they use large external monitors. The Cloud Editor offers a pleasant solution: with one click, you can reduce the width of the content. This creates more white space, making reading more comfortable on larger screens.

Below is a GIF showcasing the width adjustment feature in the new Cloud Editor, using the same example page as described above:

Stay in the Confluence Legacy Editor for good?

Of course, we could have left the page content in the Legacy Editor without doing anything. However, it is unclear how long Atlassian will maintain the Legacy Editor. Also, none of the new Cloud Editor options are available in the Legacy Editor. These new features make using Confluence Cloud more attractive and user-friendly. For example, you can insert macros using a slash (/) instead of using the curly brace ({). Also, the new editor visually enhances the page content with more generous indents and spacing. Furthermore, as shown above, you can easily switch the page layout from wide to narrow (and back).

After some hesitation and initial tests, we converted all pages to the new editor. This used to be done page by page. Since 2023, space administrators can convert all pages in a Confluence space to the new editor in bulk. Rest assured: if something goes completely wrong during conversion, you can always switch back to the Legacy Editor in the page history.

Atlassian supplies excellent documentation on converting content to the Confluence Cloud editor.

Step #3: Exploring new features in Confluence Cloud

We recommend adapting to Confluence Cloud’s unique features rather than trying to replicate Confluence Data Center/On-Premise/Server functions and macros exactly. Many of these functions and macros either aren’t available or are limited in the Cloud version, and trying to replicate them exactly can be frustrating.

💡 The upside: Confluence Cloud has many useful built-in features, rendering many self-built solutions or external apps unnecessary. This simplifies overall Confluence processes significantly.

In addition to the editor functions mentioned above, Confluence Cloud offers various features that improve usability and simplify content administration. Here’s an incomplete list of our favorites:

Moving

Move pages in the page navigation by using drag & drop.

Options in the page navigation

When hovering over a page in the page tree, you are offered many useful options. For example, you can create a child page, whiteboard, or database by clicking the “plus” sign.

Also, you can quickly edit, rename, copy, move, archive or delete a page, among other options (depending on permissions).

Archiving

There is no official archiving function in Confluence On-Premise (Data Center or Server). You had to buy an app as an extension or use creative workarounds. In Confluence Cloud, archiving content is now a standard function. Pages in the archive are not indexed in the search function by default, which improves search performance.

Publishing content

When creating and editing Confluence content, Confluence Cloud users have useful built-in functions at their disposal. For example, use “Schedule publish” and select the desired time for publication. Or use the option “Publish as a blog,” which will turn a page into a blog post. Options like these used to require buying a third-party app on Confluence Data Center or Server.

Banners and emojis

In Confluence Cloud, a banner image can be incorporated into the header of a page. In addition, an emoji can be inserted before the page title or for subheadings.

What initially looks like a mere gimmick soon proves to be an attractive way to make pages stand out from the crowd and draw attention to essential elements.

Confluence Cloud Migration – our Summary

Migrating Confluence from On-Premise (Data Center/Server) to Cloud requires clear procedures, attention to detail, and teamwork. As Part 1 of this migration guide explained, the Cloud migration itself went smoother than expected. However, exploring the Cloud editor and converting and rebuilding pages post-migration was time-consuming, spanning several weeks.

Naturally, it can be frustrating to find that certain well-established processes and templates aren’t possible in Confluence Cloud due to the absence of specific macros. However, this also offers a chance to review and streamline processes and content. Confluence Cloud also offers a big template library that embraces the built-in Cloud capacities.

💡 Keep in mind that Confluence Cloud, despite the same name, is a completely different software from Confluence On-Premise with Data Center/Server. Once we overcame the initial disappointment about its limitations, we discovered the array of new functionalities in Confluence Cloud. At bitvoodoo, even barely a few months after the migration, we were getting so used to Confluence Cloud that we wondered how we had managed to work without it all this time 😄. As of 2024, nobody misses the Confluence On-Premise editor; the Cloud editor is the standard used in all our teams, and we couldn’t imagine ever going back.

Our advice from experience: don’t be discouraged by initial disappointments. Experiment with the new Cloud features, use Atlassian’s helpful tools and resources and embrace the surprises!

Are you in the process of migrating Confluence Data Center or Server to Cloud? Reach out to bitvoodoo to learn more about migrating to Confluence Cloud.

Suggested reading:

• Access part 1 of this migration blog post, covering content review, clean-up, and the migration process.
• Read the detailed Cloud Migration Paths of bitvoodoo apps in our documentation.