Tutorial: Convert HTML to PDF

Learning Objectives

In this tutorial, you’ll learn how to:

  • Convert HTML content to PDF documents using Aspose.PDF Cloud API
  • Control page dimensions, margins, and orientation
  • Implement HTML to PDF conversion in different programming languages
  • Troubleshoot common HTML conversion issues

Prerequisites

Before starting this tutorial, make sure you have:

  • An Aspose Cloud account (You can sign up for free)
  • Your Client ID and Client Secret from the Aspose Cloud dashboard
  • Basic understanding of HTML and web content
  • Familiarity with REST API concepts

Practical Scenario

Imagine you’re developing a reporting tool that needs to convert dynamically generated HTML reports into downloadable PDF documents. The PDFs need to be properly formatted with specific page dimensions and margins to match your company’s branding guidelines.

Step-by-Step Implementation

1. Authentication Setup

First, we need to authenticate with the Aspose.PDF Cloud API to get an access token:

curl -v "https://api.aspose.cloud/connect/token" \
-X POST \
-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json"

The response will include an access token that we’ll use for subsequent API calls.

2. Converting HTML to PDF from a URL

The simplest way to convert HTML to PDF is by providing a URL:

curl -v "https://api.aspose.cloud/v3.0/pdf/create/web?url=https://example.com" \
-X GET \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
--output example_com.pdf

3. Controlling Page Dimensions and Layout

For more control over the output, you can specify dimensions, margins, and orientation:

curl -v "https://api.aspose.cloud/v3.0/pdf/create/web?url=https://example.com&width=8.5&height=11&isLandscape=false&marginLeft=0.5&marginRight=0.5&marginTop=0.5&marginBottom=0.5" \
-X GET \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
--output example_com_formatted.pdf

This example creates a PDF with US Letter dimensions (8.5 x 11 inches) in portrait mode with 0.5-inch margins on all sides.

4. Converting HTML from Storage

If you have HTML files stored in Aspose Cloud Storage, you can convert them directly:

# First, upload the HTML file
curl -v "https://api.aspose.cloud/v3.0/pdf/storage/file/report.html" \
-X PUT \
-H "Content-Type: multipart/form-data" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F file=@/path/to/your/report.html

# Then, convert the HTML file to PDF
curl -v "https://api.aspose.cloud/v3.0/pdf/create/web?srcPath=report.html" \
-X GET \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
--output report.pdf

5. Implementing in C#

Here’s how to implement HTML to PDF conversion in C#:

using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text.Json;
using System.Threading.Tasks;

namespace AsposeHtmlToPdfTutorial
{
    class Program
    {
        // Your Aspose Cloud credentials
        private const string ClientId = "YOUR_CLIENT_ID";
        private const string ClientSecret = "YOUR_CLIENT_SECRET";
        private const string BaseUrl = "https://api.aspose.cloud/v3.0/pdf";
        private const string AuthUrl = "https://api.aspose.cloud/connect/token";

        static async Task Main(string[] args)
        {
            // Step 1: Authenticate and get access token
            var token = await GetAccessToken();
            
            // Step 2: Convert HTML URL to PDF with custom dimensions
            await ConvertUrlToPdf(
                "https://example.com", 
                "example_output.pdf", 
                token,
                width: 8.5,
                height: 11.0,
                isLandscape: false,
                marginLeft: 0.5,
                marginRight: 0.5,
                marginTop: 0.5,
                marginBottom: 0.5
            );
            
            Console.WriteLine("Conversion completed successfully!");
        }

        static async Task<string> GetAccessToken()
        {
            using var client = new HttpClient();
            var content = new FormUrlEncodedContent(new[]
            {
                new KeyValuePair<string, string>("grant_type", "client_credentials"),
                new KeyValuePair<string, string>("client_id", ClientId),
                new KeyValuePair<string, string>("client_secret", ClientSecret)
            });

            var response = await client.PostAsync(AuthUrl, content);
            var responseString = await response.Content.ReadAsStringAsync();
            var authResponse = JsonSerializer.Deserialize<JsonElement>(responseString);
            
            return authResponse.GetProperty("access_token").GetString();
        }

        static async Task ConvertUrlToPdf(
            string url, 
            string outputFileName, 
            string token,
            double width = 0,
            double height = 0,
            bool isLandscape = false,
            double marginLeft = 0,
            double marginRight = 0,
            double marginTop = 0,
            double marginBottom = 0)
        {
            using var client = new HttpClient();
            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
            
            // Build the request URL with parameters
            string requestUrl = $"{BaseUrl}/create/web?url={Uri.EscapeDataString(url)}";
            
            // Add optional parameters if provided
            if (width > 0) requestUrl += $"&width={width}";
            if (height > 0) requestUrl += $"&height={height}";
            requestUrl += $"&isLandscape={isLandscape}";
            if (marginLeft > 0) requestUrl += $"&marginLeft={marginLeft}";
            if (marginRight > 0) requestUrl += $"&marginRight={marginRight}";
            if (marginTop > 0) requestUrl += $"&marginTop={marginTop}";
            if (marginBottom > 0) requestUrl += $"&marginBottom={marginBottom}";
            
            var response = await client.GetAsync(requestUrl);
            response.EnsureSuccessStatusCode();
            
            using var outputStream = File.Create(outputFileName);
            await response.Content.CopyToAsync(outputStream);
        }
    }
}

6. Implementing in Python

Here’s the Python implementation for HTML to PDF conversion:

import requests
import json

# Your Aspose Cloud credentials
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"
base_url = "https://api.aspose.cloud/v3.0/pdf"
auth_url = "https://api.aspose.cloud/connect/token"

def get_access_token():
    """Authenticate with Aspose Cloud and get access token"""
    auth_data = {
        'grant_type': 'client_credentials',
        'client_id': client_id,
        'client_secret': client_secret
    }
    
    headers = {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Accept': 'application/json'
    }
    
    response = requests.post(auth_url, data=auth_data, headers=headers)
    response_json = response.json()
    
    return response_json['access_token']

def convert_url_to_pdf(url, output_file_name, token, **kwargs):
    """Convert HTML URL to PDF with optional parameters"""
    headers = {
        'Authorization': f'Bearer {token}',
        'Accept': 'application/json'
    }
    
    # Create request URL with parameters
    params = {'url': url}
    
    # Add optional parameters
    optional_params = ['width', 'height', 'isLandscape', 
                      'marginLeft', 'marginRight', 'marginTop', 'marginBottom']
    
    for param in optional_params:
        if param in kwargs and kwargs[param] is not None:
            params[param] = kwargs[param]
    
    response = requests.get(
        f"{base_url}/create/web",
        headers=headers,
        params=params,
        stream=True
    )
    
    if response.status_code == 200:
        with open(output_file_name, 'wb') as output_file:
            for chunk in response.iter_content(chunk_size=1024):
                output_file.write(chunk)
        print(f"Conversion completed. PDF saved as {output_file_name}")
    else:
        print(f"Error converting file: {response.text}")

def main():
    # Get access token
    token = get_access_token()
    
    # Convert HTML URL to PDF with custom dimensions (US Letter)
    convert_url_to_pdf(
        "https://example.com",
        "example_output.pdf",
        token,
        width=8.5,
        height=11.0,
        isLandscape=False,
        marginLeft=0.5,
        marginRight=0.5,
        marginTop=0.5,
        marginBottom=0.5
    )

if __name__ == "__main__":
    main()

Try It Yourself

  1. Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your actual Aspose Cloud credentials
  2. Choose a website URL to convert or prepare an HTML file
  3. Execute the code in your preferred language
  4. Experiment with different page dimensions, margins, and orientation settings
  5. Open the resulting PDF and check the conversion quality

Troubleshooting Tips

  • Incomplete Rendering: If elements are missing in the PDF, ensure that all CSS and JavaScript are accessible to the API. Consider using locally hosted resources.
  • Authentication Errors: Verify your Client ID and Client Secret. These can be found in your Aspose Cloud dashboard.
  • URL Encoding: When passing URLs with special characters, ensure they are properly URL-encoded to avoid parsing errors.
  • Timeout Issues: For large or complex HTML pages, the API might timeout. Consider breaking content into smaller chunks or optimizing the HTML.
  • External Resources: If your HTML includes external resources (images, CSS, fonts), make sure they are accessible to the API. Resources behind authentication might not render correctly.

What You’ve Learned

In this tutorial, you’ve learned how to:

  • Authenticate with the Aspose.PDF Cloud API
  • Convert web pages to PDF by URL
  • Control the page dimensions, margins, and orientation of the output PDF
  • Convert HTML files stored in Aspose Cloud Storage
  • Implement HTML to PDF conversion in C# and Python
  • Handle common conversion issues

Next Steps

Now that you’ve mastered HTML to PDF conversion, you might want to try:

Further Practice

Try these exercises to reinforce your learning:

  1. Create a simple web application that lets users input a URL and receive a converted PDF
  2. Modify the code to handle authentication-protected web pages
  3. Implement a solution for batch converting a directory of HTML files
  4. Create a configuration system to save and reuse different page dimension presets

Helpful Resources