Migrating from other tab solutions to Navitabs

This article is about switching to “Navitabs - Tabs for Confluence” after having used another tab app from the Marketplace. It outlines how to find and replace tab macros on your on-premise instance before migrating them to the Cloud.

For migration help from Navitabs Server/DC to Cloud, consult this page: How to migrate Navitabs
For Macro Toolbox, consult this page: Migrating from Macro Toolbox to Navitabs
For Enterprise Theme, consult this page: Migrate Enterprise Theme content to the Cloud

1. Find & replace existing tab macros

This needs to be done on your On-Premise instance, i.e. before you try to migrate to Confluence Cloud!

Install the app Navitabs - Tabs for Confluence DC/Server. You can use the app for free for 30 days. Insert the license key.
Install the app Search and Replace (available for Server but can also be installed manually on Data Center). You can use the app for free for 30 days, but we recommend supporting the app vendor and buying a paid license. Insert the license key.
Open the Settings of the Search and Replace app in the global navigation.
Use the tab “Search and Replace” (NOT “Search and Replace Macros”!). This will open this interface:
“Search and Replace” app interface

Replace the existing tab macros with Navitabs macros “Localtabgroup” and “Localtab”

We strongly advise you to use the Search and Replace option for a single page first.

As a first test, navigate to a page where any of the existing tab macros are present.
Select "Scope=Page" and write the name of a page containing any of the tab macros.
In the field "Search for," type the wrapper macro name of your existing solution (see table below).
In the field "Replace with," write the name of the Navitabs macro: “localtabgroup” (see table below).
Click "Show Occurrences". A list of all occurrences will appear below the interface.
Click "Replace all" and accept the warning message.
Repeat steps 2-6 with the macro name of the individual tab macro.
Reload the affected page and check if the replacements were successful. If this is the case, proceed to search & replace of the entire instance (global) ⤵️ .

Switch to “Scope = Global”.
In the field "Search for," type the macro name of your existing solution (see table below).
⚠️ Always start by replacing the wrapper/group macro, only replace the individual tabs afterwards.
In the field "Replace with," write the macro name of the Navitabs macro. Start with “localtabgroup” (wrapper) in the first round and replace “localtab” (individual tab macro, see table below) in a second round.
Click "Show Occurrences". A list of all occurrences will appear below the interface.
Click "Replace all" and accept the warning message.

🎉 Success! You have merged your existing tabs to Navitabs. 🎉

List of tab macro names and their equivalent in Navitabs

This list is evolving and other tab apps will appear here in the future.

Spectrum Content Formatting for Confluence

	Spectrum Content Formatting for Confluence (Link)	Navitabs replacement	Notes
Group/ tab wrapper macro ⚠️ Replace this wrapper macro first!	Name: SP Group macro Macro: tabs-group	Name: Navitabs Tab Group macro Macro: localtabgroup
Individual tab macro	Name: SP Tab macro Macro: tab-pane	Name: Navitabs Tab macro Macro: localtab	Existing tab names will get lost in the replacement process; you will have to add them again in the Localtab macro.
Horizontal tabs
	group: horizontal-nav-group	localtabgroup	The default orientation is horizontal
	individual: horizontal-nav-item	localtab	Orientation inherited by group macro
Vertical tabs
	group: vertical-nav-group	localtabgroup	The default orientation is horizontal. You can change it to vertical in the macro settings
	individual: vertical-nav-item	localtab	Orientation inherited by group macro

Enterprise Theme for Confluence

Consult the migration manual: Migrate Enterprise Theme content to the Cloud - it should not be necessary to replace Tab Content Wrapper and Tab Element since we’ve built an automatic migration path for these macros. If you still want to follow the Search and Replace routine, use the following macro names.

Enterprise Theme for Confluence (Link)

Navitabs replacement

Group/ tab wrapper macro

⚠️ Replace this macro first!

Name: Tab Content Wrapper

Macro: gu-tabs

Name: Navitabs Tab Group macro

Macro: localtabgroup

Individual tab macro

⚠️ Replace this macro only after having replaced the wrapper macro gu-tabs!

Name: Tab Element

Macro: gu-tab

Name: Navitabs Tab macro

Macro: localtab

Limitations of Search and Replace

If your tabs names contained icons, these will be lost.
If your tabs were formatted in a specific way (tab design, vertical orientation, height, etc.), these settings will be lost. However, you can re-assign the settings in the macros Tab Group, Tab Macro and Tab Wizard once you have migrated to Confluence Cloud (see below).

2. Migrate to Navitabs Cloud

Now that the macros have been replaced by Navitabs macros, you can follow the migration steps as pointed out here: How to migrate Navitabs from Server / Data Center to Cloud

3. Add new tabs with Navitabs Cloud

Add the Tab Group macro to a page.
Add Tab macros inside Tab Group.
Save your page.

Alternatively, use the Tab Wizard to create tabs based on child pages, labels, or your own selection.