HTML Rendering Options in Python

Use a format-specific rendering-options class with the matching output device. General settings control page layout, background color, CSS media, and resolution; format-specific settings control PDF properties, raster-image output, or DOCX font embedding.

Aspose.HTML for Python via .NET provides PdfRenderingOptions, ImageRenderingOptions, DocRenderingOptions, and XpsRenderingOptions. Each class inherits common settings from RenderingOptions and adds properties for its output format.

Rendering Options vs. Save Options

Rendering options and save options configure different API workflows:

API workflow	Options	Typical call
High-level conversion	PdfSaveOptions, ImageSaveOptions, DocSaveOptions, or XpsSaveOptions	Converter.convert_html(...)
Rendering pipeline	PdfRenderingOptions, ImageRenderingOptions, DocRenderingOptions, or XpsRenderingOptions	document.render_to(device) or renderer.render(device, source)

Do not pass save options to a rendering device. For ordinary format conversion, the high-level Converter API is usually the shorter workflow. Use rendering options when the application works directly with a rendering device.

General Rendering Options

The base RenderingOptions class supplies settings shared by PDF, image, DOCX, and XPS output.

Setting	What it controls
page_setup	Output page size, margins, first/left/right page rules, and content-based page layout.
background_color	Color painted behind rendered content where the document does not supply its own background.
css.media_type	Whether @media screen or @media print rules are applied during rendering.
horizontal_resolution, vertical_resolution	Output resolution. For raster output, DPI affects the pixel dimensions of pages defined in physical units. It does not restore detail missing from source bitmaps or sharpen vector text in PDF, XPS, or DOCX.

The following example configures a page size, margins, background color, print CSS, and automatic width adjustment before rendering HTML to PDF:

1. Load the HTML document.
2. Create the rendering-options object that matches the output device.
3. Configure the required page and CSS settings.
4. Create the output device with those options.
5. Render the document to the device.

import os
import aspose.html as ah
import aspose.html.drawing as dr
import aspose.html.rendering as rn
import aspose.html.rendering.pdf as rp
import aspose.pydrawing as pd

data_dir = "data"
output_dir = "output"
os.makedirs(output_dir, exist_ok=True)

input_path = os.path.join(data_dir, "document.html")
output_path = os.path.join(output_dir, "document-layout.pdf")

with ah.HTMLDocument(input_path) as document:
    options = rp.PdfRenderingOptions()
    options.page_setup.any_page = dr.Page(
        dr.Size(800, 600),
        dr.Margin(30, 30, 30, 30),
    )
    options.page_setup.adjust_to_widest_page = True
    options.background_color = pd.Color.alice_blue
    options.css.media_type = rn.MediaType.PRINT

    with rp.PdfDevice(options, output_path) as device:
        document.render_to(device)

The numeric page and margin values are pixels. Use Length.from_inches(), Length.from_millimeters(), or another explicit unit when physical dimensions are required. adjust_to_widest_page can expand the configured page width to fit the widest content, which helps prevent horizontal clipping but may produce a nonstandard page width.

PDF Rendering Options

PDF rendering options add document information, JPEG compression quality, form-field handling, encryption, and tagged-PDF output.

Property	Purpose
document_info	Sets PDF title, author, subject, keywords, and other document information.
jpeg_quality	Controls JPEG compression quality when raster content is encoded as JPEG. It does not affect vector text or shapes.
form_field_behaviour	Keeps generated PDF form fields interactive or flattens them into page content.
encryption	Accepts PdfEncryptionInfo with user and owner passwords, permissions, and an encryption algorithm. If it is not set, the PDF is not encrypted.
is_tagged_pdf	Adds a tag structure to the generated PDF when set to True.

This concise configuration adds PDF metadata and flattens form fields. Use INTERACTIVE instead when users must complete the form after conversion:

options = rp.PdfRenderingOptions()
options.document_info.title = "Quarterly Report"
options.document_info.author = "Example Company"
options.document_info.subject = "Financial summary"
options.form_field_behaviour = rp.FormFieldBehaviour.FLATTENED

The user password controls opening the encrypted PDF. The owner password and PdfPermissions control permitted operations. Choose an encryption algorithm that meets the security requirements of the application; do not treat legacy RC4 encryption as suitable for sensitive documents.

Image Rendering Options

Image rendering options select the raster format and control TIFF compression, graphics antialiasing, and text hinting.

Property	Purpose
format	Selects PNG, JPEG, BMP, GIF, or TIFF. The default is PNG.
compression	Selects TIFF compression. The default is LZW; the property does not control JPEG quality.
use_antialiasing	Smooths rasterized edges. It is enabled by default.
text	Provides text-rendering settings such as use_hinting.

The next example renders HTML to TIFF with lossless LZW compression, 150 dpi output resolution, antialiasing, and text hinting:

import os
import aspose.html as ah
import aspose.html.drawing as dr
import aspose.html.rendering.image as ri

data_dir = "data"
output_dir = "output"
os.makedirs(output_dir, exist_ok=True)

input_path = os.path.join(data_dir, "document.html")
output_path = os.path.join(output_dir, "document.tiff")

with ah.HTMLDocument(input_path) as document:
    options = ri.ImageRenderingOptions(ri.ImageFormat.TIFF)
    options.compression = ri.Compression.LZW
    options.horizontal_resolution = dr.Resolution.from_dots_per_inch(150.0)
    options.vertical_resolution = dr.Resolution.from_dots_per_inch(150.0)
    options.use_antialiasing = True
    options.text.use_hinting = True

    with ri.ImageDevice(options, output_path) as device:
        document.render_to(device)

Higher DPI can produce more pixels and a larger raster file when the page uses physical units. It cannot add detail to a low-resolution source image. Antialiasing smooths edges, while text hinting adjusts glyph placement for raster output; neither setting changes the selected page dimensions.

DOCX Rendering Options

DocRenderingOptions adds font_embedding_rule and document_format. DOCX is the supported document format, and font embedding is disabled by default.

The following example embeds the fonts used by the document to make the DOCX output more portable:

import os
import aspose.html as ah
import aspose.html.rendering.doc as rd

data_dir = "data"
output_dir = "output"
os.makedirs(output_dir, exist_ok=True)

input_path = os.path.join(data_dir, "document.html")
output_path = os.path.join(output_dir, "document.docx")

with ah.HTMLDocument(input_path) as document:
    options = rd.DocRenderingOptions()
    options.font_embedding_rule = rd.FontEmbeddingRule.FULL

    with rd.DocDevice(options, output_path) as device:
        document.render_to(device)

FULL can increase the output size, and a font’s license may restrict embedding. When fonts are not embedded, they must be installed on the system where the DOCX file is displayed to preserve the intended appearance.

XPS Rendering Options

XpsRenderingOptions uses the general page, background, CSS media, and resolution settings described above. It does not add format-specific properties comparable to PDF encryption, TIFF compression, or DOCX font embedding. Create XpsRenderingOptions, configure only the common settings required by the result, and pass it to XpsDevice.

Common Rendering Issues

Problem	Likely cause and fix
Content is clipped horizontally	The page is narrower than the rendered content. Increase the page width, reduce margins, or enable adjust_to_widest_page when a variable page width is acceptable.
Fonts are missing or substituted	Install the required fonts in the rendering environment. For DOCX, consider FontEmbeddingRule.FULL when the font license allows embedding.
Output uses the wrong CSS layout	Set options.css.media_type to MediaType.PRINT or MediaType.SCREEN to match the intended stylesheet rules.
Raster output looks blurred	Increase output resolution when more output pixels are needed, keep antialiasing enabled, and provide source images with sufficient pixel dimensions. DPI cannot recover detail absent from the source.

Related Guides

• Rendering Devices – select the output device for PDF, XPS, DOCX, or raster images.
• Renderers – select a source-specific renderer and process multiple documents or use a timeout.
• Convert HTML to PDF – use PdfSaveOptions with the high-level converter workflow.
• Convert HTML to Images – select raster formats with ImageSaveOptions.
• Convert HTML to DOCX – configure DOCX conversion with DocSaveOptions.

Other Platforms

• Rendering Options in C#
• Fine-Tuning Converters in Java

Try Online Conversion Tools

Use the free online HTML applications for quick manual conversions. Use the Aspose.HTML for Python via .NET rendering API when output settings must be controlled in application code.