Converting non-LaTeX Math Macros to LaTeX Math Macros

This article describes the process for permanently converting non-LaTeX Math macros to LaTeX Math macros.

This tool makes it simple to handle migration compatibility issues. Non-LaTeX macros can be easily converted to LaTeX Math macros without data loss, making your server-to-cloud migration more compatible.

This is an alternative to using user macros as described in is developed because user macros are not available in the cloud.

  • The tool used to prepare migration is only available on the LaTeX Math server.

  • The page(s) can be migrated from the server to the cloud. Templates cannot be migrated.

  • Administrators and users must modify or recreate all templates in their cloud instance once the migration is complete.

  • Run the migration on a staging instance first to ensure successful migration of all content.

  • The Prepare Migration wizard will change the macro key names for all spaces or specific space(s).



You must first obtain the macro key to convert non-LaTeX Math macros to LaTeX Math macros. To obtain the macro key, perform the following:

  1. Navigate to the source page containing the macro you want to migrate.

  2. Go to> View storage format. The storage format details window is displayed.
    For example:

    ac:structured-macro ac:name="ppl mathjax inline macro" ac:schema-version="1" ac:macro-id="404b812b-323b-44ec-af01-a7748fb8146b"><ac:parameter ac:name="equation">e=mc^2</ac:parameter></ac:structured-macro>
  3. Look for the following details:

    1. Source Macro key: Under <ac:structured-macro ac:name="ppl mathjax inline macro" and copy the value of ac:name. For example ppl mathjax inline macro.

    2. Source Math combined in: Under<ac:parameter ac:name="equation">e=mc^2</ac:parameter> and copy the value of ac:name. For example equation.

note Make sure you copy the correct macro key. An invalid macro key will result in unsuccessful migration.


Prepare Migration

Perform the following to prepare a page or a space for migration:

  1. Go to > Manage apps > APPFIRE CONFIGURATION > LaTex Math. The Configure LaTex Math page is displayed.


  2. Select the Migration Settings tab and click the Prepare Migration button. The Migration Preparation window is displayed.

    3. Enter the following information to map the macro key names and the relevant parameter:

For more information, refer to Prerequisites.

Parameter Name


Parameter Name


Source Macro key

Enter the macro key to be replaced with the cloud version. The macro key name varies with each macro.

Source Math combined in

Enter the parameter name of the relevant math expression or equation in the server instance.

Target Macro key

Specify the output type of math macro. Incase of LaTeX Math,

  • mathinline is the Target Macro key for inline macro.

  • mathblock is the Target Macro key for block macro.

Select all unprepared for migration spaces

Select the checkbox to prepare all the unprepared pages across all the spaces for migration.

To select a particular space(s), uncheck the Select all unprepared for migration spaces box and specify the space key(s) in the text box.

The Source Macro key and the Target Macro key must be of the same type. For example, if your Source Macro key is an inline type macro, then the Target Macro key should also be an inline type macro.

4. Click Prepare Migration.

A Finished Migration Preparation progress bar is displayed, along with the number of pages that matched the given criteria and were migrated. Invalid data provided results in migration failure. The Prepare Migration page displays details about the page(s) and space(s) that were impacted.



Once you have completed Prepare Migration for all spaces, you must run Confluence Cloud Migration Assistant (CCMA) to migrate space(s) from server to cloud.

If you face any errors or breakages on the page(s) in the cloud version, you must rename the macro key name manually for each such instance. If you are unable to resolve the issues, please contact our Support for assistance.



com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'appfire-docs-analytics' is unknown.