How can Word limitations affect my export?
When exporting content from Confluence sometimes an export error can occur or alternatively, incorrect formatting within the generated export occurs. Such behaviour can be caused by a number of different reasons, such as a bug within the app, issues with content on the page and/or related connection settings configurations.
However, issues of this kind can also be the result of limitations within Microsoft Word and in this article we have listed the most encountered problems amongst our users due to these limitations. This includes:
- list numbering or bullet signs are not rendered in large exports
- an export error occurs when exporting content that includes a lot of list levels
- an export error occurs when exporting a table with many columns
- some images or diagrams become unreadable in the export
Limitation 1 - List numbering is not preserved
When exporting many pages from Confluence which contain a lot of list styles, the generated export does not contain the correct list formatting for some list objects.
This problem relates to Microsoft Word having a limitation on the number of list items that can be included in a Word file. This means that MS Word stops applying list formatting to list objects once it reaches 2046 list items. Subsequently, if you export Confluence pages with more than 2046 list items, the lists after this limit is reached will be added without any numbering and/or bullet symbol.
To clarify (see below), Microsoft Word defines one individual list as a list item and the limitation does not apply to a single list which can have over 2046 points.
To prevent this issue from occurring you would need to ensure that the exported content contains less than 2046 list items.
Limitation 2 - An export error occurs when exporting content with a lot of list levels
When exporting list content from a page that has more than 9 list levels defined, an export error is generated in Confluence.
If you have a Confluence page containing a list with more than 9 list-levels this will generate an export error within Confluence as soon as you start the export. Unfortunately, MS Word does not support more than 9 list-levels within a Word document. This differs in comparison to Confluence where you can have a higher amount of list-levels defined. For example, if you try adding multiple list levels in a Word document you will soon notice that after the ninth list-level no new levels can be added.
In such cases where this error occurs it is possible to identify this as the cause via the logs and finding this message:
Caused by: com.k15t.scroll.core.extension.exporter.ExporterException: messages.asposeexception.maxlistlevel
To prevent this issue from occurring you would need to ensure that your defined lists on Confluence pages have 9 or less levels.
Limitation 3 - An export error occurs when exporting large tables
When exporting a table from a page which has more than 63 columns defined, an export error is generated in Confluence.
Microsoft Word has a limitation for the number of columns that can be defined in a Word document. The limit for the amount of columns is set to 63 and if you try to add additional columns you will receive this notification:
This means that if you attempt to export a Confluence page that contains tables of this size and format, the Word library that we use to generate the export will display an error. In such cases where this error occurs it is possible to identify this as the cause via the logs and finding this message:
"Caused by: java.lang.IllegalStateException: More than 63 cells per row is not supported for this file format."
To prevent this issue from occurring you would need to ensure that the tables on the page do not exceed the 63 column limit that is set in MS Word.
Please note, this issue can also occur for Excel tables (via the Excel macro on a Confluence page) that contain many columns due to the content being transformed into a table in the generated Word export.
Limitation 4 - Some images and diagrams become unreadable in the generated Word export
When exporting a large image (and/or image that is provided by a third-party macro) that is on a Confluence page, the image can become unreadable in the generated export.
Microsoft Word is unable split a big image over multiple pages. Instead, Word automatically scales down the image to fit on the page the problem and with this approach it reduces the size of the image. In cases where the image/diagram is very large, this can also lead to the scaling affecting some elements of the text/shapes/objects also being made smaller and unreadable.
When an image or a diagram is very large, you can try to resize the image to fit the Word page. Alternatively, it may be required to separate the image or the diagram into different sections to break it up over multiple pages.
Limitation 5 - Content that extends the length of a page, nested within a Scroll Content Block macro, is not kept together
When exporting some text and a large object that extends beyond a page within the generated Word export (eg. a large table), the Scroll Content Block macro does not keep all the content together in the generated export. Instead, a page break is added between the text and the large object.
This behaviour occurs due to the way in which the keep-with-next property works in MS Word. Unfortunately, in this scenario our app is unable to change this behaviour. This is because when the content exceeds the page length, our Scroll Content Block macro will override the keep-with-next property but the logic in MS Word is unable to determine the optimal place for adding a page break. This results in the pagebreak being placed after the text and prior to the large object (eg. Scroll Code table style).
Unfortunately, in such situations, there is not an optimal workaround and will likely require reducing the size of the large object that follows the text (where possible).
Limitation 6 - Macros and tables include extra line break when included in an empty list style
When an admonition macro (ie. Info, Warning, Tip, Note), Panel macro, Code Block macro or table is included in an empty list style, an additional line break, which is not shown in the Confluence page view, is added in the export.
Microsoft Word does not support tables being placed inline within numbered or bulleted lists. This means for tables and macros (which are rendered as tables in the export) an extra line will be added even thought this additional paragraph is not shown in the Confluence page view on Server and Data Center.
Unfortunately, in this scenario our app is unable to change this behaviour. It is not possible to workaround this formatting post-export because MS Word does not support tables being placed inline within a list.