DocumentationAEM GuidesAEM Guides Documentation

Work with the Native PDF engine v2

Last update: June 17, 2026

CREATED FOR:

  • User

The new publishing engine Native PDF engine v2, is based on an upgraded PDF generation framework and includes changes to font handling, CSS processing, and rendering behavior.

As a result, PDF output generated using the new publishing engine may differ from output generated using the existing PDF engine (Native PDF engine v1). Differences may be visible in areas such as text layout, spacing, styling, image rendering, and footnote formatting.

For example, the Native PDF engine v2 supports OpenType fonts, whereas the Native PDF engine v1 primarily relies on TrueType fonts. Similar rendering enhancements can affect the overall appearance of generated PDFs.

For details on how to enable the Native PDF engine v2 in your environment, view Configure the new publishing engine for Native PDF.

If you want to restore the appearance of PDF output generated by the Native PDF engine v1 while using the Native PDF engine v2, you may need to update your custom CSS. The recommended CSS changes described below can help maintain output consistency after enabling the new setting.

Description
Recommended CSS update
Scaled images may appear different because of changes in image rendering behavior.
To restore image rendering behavior, add:

image-rendering: pixelated
Table of contents (TOC) leader alignment may appear slightly different because of changes in leader rendering behavior.
To restore TOC leader alignment, adjust the styling of the TOC leader elements in your custom stylesheet. The required CSS changes may vary depending on your TOC layout and formatting.
Text spacing and line wrapping may differ because of changes in font rendering and glyph layout processing.
If your stylesheet uses the sans-serif font family or fonts that exhibit spacing differences, add:

-ro-glyph-layout-mode: quality;
Footnote references may no longer appear as superscript markers because of changes to the default footnote styling.
To restore superscript-style footnote markers, add:

.fn::footnote-marker
{ content: counter(footnote) " ";
vertical-align: super;
font-size: 65%;}
Underlined text may appear with more space between the text and the underline because of changes in underline positioning.
To restore underline positioning, use the text-underline-offset property and adjust the offset value as needed. For example:

text-decoration: underline;
text-underline-offset: -0.1em;
The spacing between list markers and list item text may differ because of changes in list rendering behavior.
To restore spacing, increase the left padding for list items. For example:

.step {
margin-top: 0.3rem;
margin-bottom: 0.5rem;
padding-left: calc(1.5rem + 1ch);}
Spacing before headings may differ because of changes in margin collapsing behavior.
To restore the spacing, review the margins of adjacent elements and reduce or remove overlapping top and bottom margins where needed. For example:

h1.chapter {
margin-top: 0;
}
chaptoc-body { margin-bottom: 0;
}
Checkmark markers generated with CSS may appear with different sizes or styling because they are rendered using different fallback fonts.
To render markers consistently, use a font family that contains both glyphs. For example:

::marker {
font-family: -ro-symbols !important;}
CSS-generated circular list markers may appear partially clipped or truncated because of changes in marker positioning behavior.
To restore the appearance of circular list markers, avoid using absolute positioning for the marker. If absolute positioning is required, explicitly specify an appropriate top value to correctly position the marker.
The reading order of list items in PDF/UA output may differ when list items use positioning styles such as position: relative.
To make the reading order follow the source document structure more closely, apply the following CSS property to list items:

li {
-ro-paint-reordering: avoid;}

Workarounds for known issues

The following workarounds can help address known issues in the generated PDF output when using Native PDF engine v2.

  • text-decoration css properties applied to table content are not rendered in PDF output.

    Workaround: Apply the text decoration properties to span elements within the table content instead of applying them directly to the table elements.

  • -ro-colorbar-top-left and -ro-colorbar-top-right CSS properties do not affect the color bar in PDF output.

    Workaround: Remove the corresponding values from the user style sheet in mergedHTML.json, or add !important to the property values in the document CSS so they are not overridden by the user style sheet.

  • Color bars may appear merged when the page width is constrained because color bars are not scaled down with the page size in PDF output.

    Workaround: Display the gray and colored bars on different sides of the page, or adjust the color bar settings so they do not overlap at smaller page widths.

Fixed issues with the new publishing engine

The following issues in PDF output generated using Native PDF Engine v1 are fixed in Native PDF Engine v2:

  • When generating Native PDF output for certain content, only the first page is rendered in the PDF despite the intermediate HTML containing the complete content across multiple pages. (GUIDES-28270)
  • The reading order of content in Native PDF output with accessibility settings enabled is incorrect. Page numbers from footers are read before the main content instead of at the end. (GUIDES-27790)
  • The color bar in Native PDF output does not stretch across the full page width and overlaps when the page size is customized, causing some color boxes to be hidden. (GUIDES-15505)
  • The CSS:is()pseudo-class selector is not honored in Native PDF output, resulting in styling differences compared to browser rendering. (GUIDES-11328)
recommendation-more-help
experience-manager-guides-help-product-guide