Macro Migration Limitations

Overview

This document outlines the limitations, constraints, and known issues related to migrating macros from third-party latex applications to Easy Latex Math.

Important: Please review this document carefully before performing any migrations to ensure the migration process meets your requirements.

✅ Supported Migrations

Supported Parameters

The following parameters are preserved during migration:

For mathinline / eazy-math-inline

• ✅ formula - The latex equation content

• ✅ align - Alignment settings

For mathblock / easy-math-block

• ✅ formula - The latex equation content (with CDATA extraction)

• ✅ align - Alignment settings

• ✅ anchor - Block anchor

For unit

• ✅ formula - The latex equation content

❌ Limitations & Constraints

1. Unsupported Macro Types

The following macros cannot be migrated:

• ❌ Custom or proprietary macros not listed in supported types

• ❌ Deprecated legacy macros

• ❌ Macros from applications not listed in supported sources

Workaround: Manual recreation required for unsupported macro types.

2. Parameter Mapping Limitations

Some parameters may not have direct equivalents:

3. Content Limitations

CDATA Sections

• ✅ Automatically extracted from <![CDATA[...]]> blocks in mathblock macros

• ⚠️ Nested CDATA blocks may cause parsing issues

• ⚠️ Malformed CDATA may not be extracted correctly

Special Characters

• ✅ Most latex special characters preserved

• ⚠️ XML-encoded entities may require manual verification

• ⚠️ Unicode characters should be tested after migration

Formula Complexity

• ✅ Standard latex formulas migrate successfully

• ⚠️ Extremely complex formulas should be verified after migration

• ⚠️ Package-specific latex commands may not render identically

4. Performance Limitations

Bulk Migration

• ⚠️ Sequential Processing: Pages are migrated one at a time (not parallel)

• ⚠️ No Progress Indicator: Console logging only, no UI progress bar

• ⚠️ Large Spaces: Spaces with >100 pages may take significant time

• ⚠️ No Pause/Resume: Bulk migrations cannot be paused mid-process

Recommendation: For spaces with >50 pages, consider migrating in batches during low-traffic periods.

API Rate Limits

• ⚠️ Confluence API rate limits may apply for high-volume migrations

• ⚠️ Migrations may fail if rate limits are exceeded

Workaround: Wait and retry if rate limit errors occur.

5. Scope Limitations

Page Types

• ✅ Standard Confluence pages

• ✅ Blog posts

• ❌ Comments (macros in comments not migrated)

• ❌ Templates (must be migrated manually)

Content Types

• ✅ Page body content

• ❌ Page properties macros

• ❌ Macros in custom fields

6. Rollback Limitations

• ❌ No Automatic Rollback: Migrations cannot be automatically undone

• ⚠️ Manual Rollback Required: Use Confluence page history to revert

• ⚠️ Version Increment: Each migration creates a new page version

Recommendation: Test on a copy or in a test space first.

7. Error Handling Limitations

• ⚠️ Failed migrations are logged but not automatically retried

• ⚠️ Partial failures in bulk migration will continue processing remaining pages

⚠️ Known Issues