Common image issues and best practices

This article describes common image-related issues in Tangelo and explains the recommended best practices for managing images, renditions, page inserts, and output quality.

Many image issues are caused by incorrect upload workflows, missing permissions, unsupported formats, or misunderstanding how Tangelo manages image renditions and document references.

Understanding these concepts helps avoid layout issues, missing visuals, unexpected output differences, or low-quality PDF generation.

Summary

This article helps identify common image problems and explains how to avoid them using the recommended Tangelo image workflows.

Common Issues

The Image Is Not Available in the Document

Possible causes:

• No access to the image collection
• The image was uploaded to the wrong collection
• The file was uploaded under Files instead of Images
• The image type is not supported in the current template

Best practices:

• Always upload images through the Images library
• Verify collection permissions
• Use the correct image type
• Use page inserts for full-page visuals

The Wrong Image Appears in the Document

Tangelo uses image references instead of copying image files into documents. This means:

• Replacing an image updates the image in all connected documents
• Existing image references continue pointing to the same image object

This is usually intentional behavior and helps maintain consistency across documents.

Best practices:

• Use Replace image when updating existing visuals
• Upload a completely new image only when a separate image reference is needed
• Be aware that replacing shared assets updates all connected documents

The Image Looks Different in PDF or Website Output

Different renditions can be used for different output channels.

Possible causes:

• A dedicated PDF rendition exists
• A website rendition is used instead of the base image
• Automatic renditions were generated from a lower-quality source image

Best practices:

• Upload dedicated print-quality PDF renditions for important visuals
• Use vector-based PDFs where possible
• Validate all relevant output formats before publishing

The Image Looks Blurry or Low Quality

Possible causes:

• Low-resolution source image
• JPG compression artifacts
• Rasterized graphics or text
• Scaling images beyond their intended size

Best practices:

• Use at least 300 PPI for print-quality visuals
• Use PDF for infographics, logos, and designed pages
• Use JPG mainly for photographic material
• Avoid enlarging small raster images

White Borders Appear Around Full-Page Images

This is usually caused by missing bleed in print-ready artwork.

Best practices:

• Use A4 + 3 mm bleed for full-page visuals
• Extend background colors and graphics beyond the trim edge
• Do not include crop marks in uploaded files

Page Inserts Are Missing in iXBRL Output

Possible causes:

• Deprecated PDF insertion workflow through the Files tab
• Unsupported page insert positioning

Important:

• PDFs inserted through the deprecated Files workflow are not included in iXBRL reports.
• In Text – Background page inserts are not included in iXBRL outputs.

Best practices:

• Use the supported Page Insert workflow
• Upload designed pages through the Images library
• Validate iXBRL output separately from PDF output

Content Moves Unexpectedly After Positioning an Image

Fixed image positioning affects the document layout.

Possible causes:

• Top or side positioning reserves page space
• Text wrapping changes content flow
• Section titles are pushed down by positioned images

Best practices:

• Validate the layout after positioning images
• Be careful when placing images at the top of pages
• Use page inserts for full-page designs instead of fixed-position images where appropriate

Best Practices Overview

Image Management

• Use image collections to organise assets logically
• Replace existing images instead of creating duplicates where possible
• Use meaningful image names and descriptions

File Formats

• PDF for designed pages, logos, infographics, and print
• JPG for photos
• PNG for transparency support
• SVG only when properly prepared

Output Quality

• Use dedicated print renditions for high-quality PDF output
• Use vector-based artwork where possible
• Include bleed for print-ready full-page visuals

Workflow Recommendations

• Use Images for all document visuals
• Do not use the Files tab for document images
• Use page inserts for full-page designs
• Validate PDF and iXBRL outputs separately

Remarks

• Tangelo automatically generates some renditions based on the base image.
• Replacing the base image also regenerates the iXBRL rendition.
• Legacy workflows may still exist in older environments and can affect output behavior.
• If image behavior is unclear or inconsistent, contact your Tangelo consultant or administrator.