Tabrail documentation
Tabrail moves legacy tab macros (the ones Data Center sites used, such as deck and card, ui-tabs and ui-tab, localtab-group and localtab) to Confluence Cloud's native Tabs element.
Why pages need it
After a move to Confluence Cloud, those macros have no Cloud app behind them. ui-tabs and localtab pages show an "unknown macro" box where the content was; deck pages fall back to a box of expanders. The content is still in the page, just not readable the way it was. Confluence Cloud now has its own Tabs element (type /tabs in the editor), so the content belongs there.
Set up (Confluence admin, about two minutes)
- Open Settings (gear), Apps, Tabrail tab migration.
- Teach Tabrail the native Tabs format. Confluence doesn't publish how its Tabs element
stores tab titles, so Tabrail reads it from your site once:
- On any page, type
/tabs, name the two tabs exactly Tabrail A and Tabrail B, and publish. - Paste the page link into Page link and select Learn from this page, or select Find it for me (search can take a minute to see a new page).
- You can delete the sample page afterwards. Until this is done, Tabrail converts tab groups to collapsible sections instead of Tabs.
- On any page, type
- Check Defaults and the macro pairs list. Add a pair if your old site used other tab
macros (for example a group macro
tabs-groupcontainingtab-panemacros whose title is in anameparameter).
Convert one page
Open the page, select ••• (More actions), then Convert tab macros. The dialog lists each tab group, its tabs, what it will become, and anything that needs a look. Change the options if needed and select Convert. Reload the page to see the result.
Undo last conversion puts the previous content back as a new version, as long as nobody edited the page since. After an edit, use Page history to restore the version before the conversion (the dialog tells you which one).
Convert many pages
On the admin page, step 2:
- Optionally enter space keys, then Find pages. Tabrail lists the pages you can see that contain the macros in your pairs list.
- Scan selected shows, for each page, how many groups become Tabs, sections or headings and how many need a look. Groups that need a look are listed below the table with the reason.
- Convert selected runs in batches of 5 pages. Keep "Only convert pages where every group converts cleanly" on for the first pass, then handle the rest one page at a time.
Every conversion is listed under Activity, with Undo for the most recent one on each page.
What happens to each part of a tab group
| In the old macro | After Tabrail |
|---|---|
| Group at the top level of the page | One native Tabs element, same tab titles and order |
| Tab content: text, code blocks, tables, panels, images, Jira and other macros | Moved into the tab unchanged |
| A tab group inside a tab | Headings inside the parent tab (default), or extra tabs named "Parent / Child" |
| An expand inside a tab | Heading followed by its content (default), or kept as it is; Confluence then shows it inside a legacy block, because native Tabs can't hold expands |
| A group inside a layout column | One expand per tab |
| A group inside a table cell, panel or other macro | A heading per tab followed by its content |
| Text between the tabs | Moved above or below the Tabs |
| A tab without a title | "Tab 1", "Tab 2"... |
| Macro options such as a deck id or a default tab | Not carried over; listed as a note so you can check links |
Auto-convert
Admin page, step 3: turn on Auto-convert to convert tab groups whenever a page is created or edited, optionally only in some spaces. Auto-convert only touches a page when every group on it converts cleanly; anything that needs a look is left for a person. Useful during a migration that runs in waves, or when old pages are imported or copied later.
When Tabrail leaves a group alone
- Confluence's migrated copy is missing text. During migration Confluence keeps the original macro source and its own converted copy. In rare cases the converted copy loses text (Atlassian issue CONFCLOUD-84992). Tabrail compares the two and skips the group, so the gap isn't made permanent. Restore the content by hand, then run Tabrail again.
- No tabs inside. The group macro has no tab macros in it.
- You chose to leave groups in layouts and tables alone.
Licensing and the free trial
During Atlassian's 30-day free trial, Tabrail converts up to 10 pages per site, so you can check the result on your own content. Finding pages, scanning, previews and Undo are not limited, and converting the same page again after an Undo doesn't use another slot. Auto-convert is off during the trial. Converting the rest of your site and auto-convert unlock with the paid subscription; the page dialog and the admin page show how many trial pages are used.
Without an active subscription Tabrail can still scan pages and undo conversions; converting and auto-convert need the subscription. Converted pages don't depend on Tabrail: they keep working if you uninstall it.
Support
Use the support portal linked on the Marketplace listing. Include the page link and, if you can, a screenshot of the Convert tab macros dialog.