Migrating to the Next Reader UI Template

Switching to the Next Reader UI template brings better performance, a modern design, and many built-in features. Because the architecture of the new template differs from the other ones, some of your existing customizations — such as custom scripts, specific UI settings, and footers — will require adjustments. To learn more about its advantages and limitations, see Next Reader UI Template.

This guide provides a 5-step process to help you transition your portal smoothly.

• Step 1. Choose a Testing Scope
• Step 2. Clean Up Topic Master Page
• Step 3. Adjust Settings and Branding
• Step 4. Update Footers and API Docs
• Step 5. Roll Out to the Whole Portal
• Migration FAQ

Step 1. Choose a Testing Scope

Before applying the new template to your live documentation, test it in a limited environment. Choose the option that fits your workflow:

• A single publication: The fastest way to check how your content looks. You can override the template in the publication settings without affecting the rest of the project.
• A single project: Override the portal template for a specific project, then update its publications to see how the template behaves across multiple documents.
• Sandbox portal: If you have the Sandbox portal, you can safely test the full portal-level experience with zero risk to your live documentation.

Step 2. Clean Up Topic Master Page

The Next Reader UI has navigation features built-in. If you have previously added custom scripts or snippets to your Topic Master Page for these features, you need to remove them so they don't appear duplicated:

• Previous/Next topic links: Generated automatically.
• Back to top button: Built into the template natively.

Step 3. Adjust Settings and Branding

The Next Reader UI template takes a new approach to settings, keeping the interface lightweight and pushing heavier customizations to CSS.

1. Review Reader Interface Settings: The Next Reader UI template supports a subset of the Reader Interface settings. All other styling, such as fonts, spacing, header and sidebar styling, should be moved to Branding.css. See Advanced Branding with CSS.
2. Update CSS Selectors: The HTML markup of the Next template differs from other templates. Your existing CSS rules and branding scripts will not apply and need to be rewritten.

Step 4. Update Footers and API Docs

Two specific structural elements need to be migrated differently:

• Application Footer: The Next template does not support a portal-wide Application Footer. You can move your footer content into a Topic Footer, which can still be applied to the whole portal or specific projects. See Custom Topic Footer and Header.
• API Documentation: If you have projects containing API documentation, switch from the Legacy rendering engine to Modern.

Step 5. Roll Out to the Whole Portal

Once you are happy with how the Next template looks in your test scope, it's time to apply it globally:

1. Enable the Next Reader UI at the portal level.
2. Remove any template overrides that you have set for your test projects or publications in step 1, so that they inherit the new portal-level settings.
   

As a result, your documentation is served through the Next template: faster page loading, a WCAG 2.2 AA-compliant interface, hashbang-free URLs that search engines and AI agents index properly, and built-in navigation instead of custom scripts.

Migration FAQ

Back
to top