DEV Community

IronSoftware
IronSoftware

Posted on

HTMLDOC vs IronPDF: a pragmatic comparison for 2026 .NET teams

  • Competitor technical approach/engine: Standalone command-line tool/GUI application; supports HTML 3.2 + limited HTML 4.01; no CSS support; no modern JavaScript; outputs PDF, PostScript, EPUB; written in C (source)
  • Install footprint: Binaries for Windows 10+, macOS 11+, Linux (Snap); separate executable, not a library; must be invoked via Process.Start or shell execution (source)
  • IronPDF doc links chosen:
  • What this tool is for: HTMLDOC is a command-line PDF/PostScript/EPUB generator for legacy HTML (3.2 era); designed for documentation/reports, not modern web content
  • No-guess rule applied: HTMLDOC capabilities verified from official site and Wikipedia; IronPDF API from official docs only

You open the technical specification: "Generate PDF reports from HTML templates." You reach for HTMLDOC because it's free and established. Then you see the requirements list: modern CSS layouts, JavaScript-driven charts, web fonts, responsive design. You check HTMLDOC's feature list: HTML 3.2 support, no CSS, no forms, limited Unicode.

The gap between "can generate PDFs from HTML" and "can handle 2026 web content" determines whether a tool is viable. HTMLDOC remains actively maintained for its original purpose—converting simple, static HTML documentation into PDFs. For .NET applications requiring modern web standards, the architectural mismatch often surfaces immediately during prototyping.

Understanding IronPDF

IronPDF is a .NET library that embeds a Chromium rendering engine. It processes HTML the same way Chrome does, supporting CSS3, JavaScript, web fonts, and modern DOM APIs. No external executable needed—just a NuGet package that integrates directly into your C# application.

The library targets .NET Framework 4.6.2+, .NET Core, .NET Standard 2.0, and current .NET (6, 8, 9, 10). Works on Windows, Linux, macOS, in Docker, serverless functions, and traditional ASP.NET. See the HTML to PDF guide for integration patterns.

Key Limitations of HTMLDOC

Product Status

HTMLDOC is actively maintained by its original author, with releases in September 2025, December 2024, and November 2024. It's open-source (GPL v2), free to use, and stable. However, it's intentionally scoped as a legacy HTML converter—documentation explicitly states it does not support CSS, forms, full Unicode, or modern web features.

Missing Capabilities

  • No CSS support: Cannot process <style> tags or external stylesheets; styling via deprecated HTML attributes only
  • No JavaScript execution: Static HTML only; cannot render charts, dynamic content, or interactive elements
  • HTML 3.2 + limited 4.01: Missing modern HTML5 elements (<header>, <nav>, <article>, <canvas>, <video>)
  • No web fonts: Limited to system fonts; no WOFF/WOFF2 support
  • No forms support: Cannot render PDF forms or input elements
  • Limited Unicode: Lacks support for CJK characters, Arabic, full emoji; limited to Western character sets
  • No flexbox or Grid: Cannot process modern CSS layout systems

Technical Issues

  • Process invocation overhead: Must spawn external process via Process.Start; adds latency and complexity
  • File-based I/O required: HTMLDOC reads HTML from files and writes PDF to files; no in-memory streaming
  • Command-line argument escaping: Complex HTML or file paths require careful shell escaping
  • Error handling via exit codes: Limited error reporting; must parse stdout/stderr for diagnostics
  • No .NET integration: Not a library; interop through process execution and file system

Support Status

Community support via GitHub issues and documentation. No commercial support or SLA. Project maintained by single developer.

Architecture Problems

  • External executable dependency: Must deploy htmldoc.exe (Windows) or htmldoc binary (Linux/macOS) alongside your .NET application
  • Platform-specific binaries: Different executables for Windows, macOS, Linux; deployment scripts must handle platform detection
  • Process lifecycle management: Application must handle process creation, timeout, error handling, cleanup
  • Concurrent execution complexity: Spawning multiple processes for parallel PDF generation requires careful resource management

Feature Comparison Overview

Feature HTMLDOC IronPDF
Current Status Active (legacy scope) Active (modern web)
HTML Support HTML 3.2 + limited 4.01 Full HTML5
Rendering Quality Basic (no CSS) Pixel-perfect (Chromium)
Installation External executable NuGet library
Support Community (GitHub) 24/5 engineer chat
Future Viability Intentionally legacy Modern web standards

Capability Checklist: Can HTMLDOC Handle Your Requirements?

❌ Modern Web Standards

  • ☐ CSS3 (Grid, Flexbox, variables, transforms)
  • ☐ JavaScript execution (charts, dynamic content)
  • ☐ Web fonts (WOFF/WOFF2, Google Fonts)
  • ☐ HTML5 semantic elements (<header>, <section>, <article>)
  • ☐ SVG graphics embedded in HTML
  • ☐ Responsive design (@media queries)
  • ☐ Modern image formats (WebP, AVIF)

✅ Legacy HTML Documentation

  • ✓ HTML 3.2 tables and basic formatting
  • ✓ Simple page layouts with deprecated HTML attributes
  • ✓ Table of contents generation
  • ✓ PostScript output (if needed)
  • ✓ EPUB output (if needed)
  • ✓ Command-line batch processing
  • ✓ Free and open-source

❌ Advanced PDF Features

  • ☐ Interactive PDF forms
  • ☐ Watermarks via library API
  • ☐ Digital signatures
  • ☐ Merge/split PDFs
  • ☐ Extract text from existing PDFs
  • ☐ Encryption with granular permissions
  • ☐ PDF/A or PDF/UA compliance

⚠️ .NET Integration Complexity

  • ☐ Native .NET library (no external executable)
  • ☐ In-memory HTML to PDF (no temp files)
  • ☐ Async/await support
  • ☐ Thread-safe concurrent rendering
  • ☐ NuGet package management
  • ☐ Unified cross-platform deployment

Decision criterion: If you checked any ❌ items as requirements, HTMLDOC is not the right tool.


Code Comparison: HTML String to PDF

HTMLDOC — HTML String to PDF (Process Invocation)

using System;
using System.Diagnostics;
using System.IO;

namespace HtmldocExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // HTML content (must be simple HTML 3.2)
            // No CSS, no JavaScript, no modern HTML5 elements
            string htmlContent = @"
                <html>
                <head>
                    <title>Invoice</title>
                </head>
                <body>
                    <h1>Invoice #12345</h1>
                    <table border='1' cellpadding='5'>
                        <tr>
                            <td><b>Item</b></td>
                            <td><b>Quantity</b></td>
                            <td><b>Price</b></td>
                        </tr>
                        <tr>
                            <td>Widget A</td>
                            <td>5</td>
                            <td>$25.00</td>
                        </tr>
                    </table>
                    <p><b>Total: $125.00</b></p>
                </body>
                </html>";

            // CRITICAL: HTMLDOC requires file-based I/O
            // Write HTML to temporary file
            string tempHtmlPath = Path.Combine(Path.GetTempPath(), "temp_invoice.html");
            File.WriteAllText(tempHtmlPath, htmlContent);

            // Output PDF path
            string outputPdfPath = "output.pdf";

            // Prepare HTMLDOC command-line arguments
            // Format: htmldoc [options] input.html -f output.pdf
            var startInfo = new ProcessStartInfo
            {
                FileName = "htmldoc", // Must be in PATH or use full path
                Arguments = $"--webpage --no-title --no-toc -f \"{outputPdfPath}\" \"{tempHtmlPath}\"",
                RedirectStandardOutput = true,
                RedirectStandardError = true,
                UseShellExecute = false,
                CreateNoWindow = true
            };

            try
            {
                // Execute HTMLDOC process
                using (var process = Process.Start(startInfo))
                {
                    // Wait for completion (synchronous blocking)
                    process.WaitForExit();

                    // Check exit code
                    if (process.ExitCode != 0)
                    {
                        string error = process.StandardError.ReadToEnd();
                        Console.WriteLine($"HTMLDOC failed with exit code {process.ExitCode}");
                        Console.WriteLine($"Error: {error}");
                        return;
                    }
                }

                Console.WriteLine($"PDF generated: {outputPdfPath}");
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error executing HTMLDOC: {ex.Message}");
                // Common errors:
                // - HTMLDOC not found in PATH
                // - File path contains special characters
                // - Insufficient permissions for temp file
            }
            finally
            {
                // Cleanup temp file
                try
                {
                    if (File.Exists(tempHtmlPath))
                        File.Delete(tempHtmlPath);
                }
                catch { /* Ignore cleanup errors */ }
            }
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

Deployment checklist for this approach:

  • ☐ Install HTMLDOC binary on all deployment targets (dev, staging, prod)
  • ☐ Verify HTMLDOC is in system PATH or configure full executable path
  • ☐ Ensure application has file system permissions for temp directory
  • ☐ Handle platform-specific HTMLDOC binary (htmldoc.exe on Windows, htmldoc on Linux/macOS)
  • ☐ Configure firewall/antivirus to allow process execution
  • ☐ Implement process timeout handling for long-running conversions
  • ☐ Add retry logic for transient file I/O errors
  • ☐ Monitor temp file cleanup to prevent disk space issues

IronPDF — HTML String to PDF (Native Library)

using IronPdf;

namespace IronPdfExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // HTML content (can use modern CSS3, JavaScript, etc.)
            string htmlContent = @"
                <!DOCTYPE html>
                <html>
                <head>
                    <style>
                        body { font-family: Arial, sans-serif; }
                        h1 { color: #2c3e50; }
                        table { border-collapse: collapse; width: 100%; }
                        th, td { border: 1px solid #ddd; padding: 8px; text-align: left; }
                        th { background-color: #3498db; color: white; }
                    </style>
                </head>
                <body>
                    <h1>Invoice #12345</h1>
                    <table>
                        <thead>
                            <tr>
                                <th>Item</th>
                                <th>Quantity</th>
                                <th>Price</th>
                            </tr>
                        </thead>
                        <tbody>
                            <tr>
                                <td>Widget A</td>
                                <td>5</td>
                                <td>$25.00</td>
                            </tr>
                        </tbody>
                    </table>
                    <p><strong>Total: $125.00</strong></p>
                </body>
                </html>";

            // Instantiate renderer (Chromium engine in-process)
            var renderer = new ChromePdfRenderer();

            // Render HTML to PDF (in-memory, no temp files)
            var pdf = renderer.RenderHtmlAsPdf(htmlContent);

            // Save result
            pdf.SaveAs("output.pdf");
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

Deployment checklist for this approach:

  • ☑ Install NuGet package IronPdf (one-time, via standard package management)
  • ☑ Native libraries automatically included and loaded (no manual steps)
  • ☑ Works cross-platform (Windows, Linux, macOS) from same package
  • ☑ No external executable dependencies
  • ☑ No temp file management required

See the HTML string to PDF tutorial for advanced scenarios including external asset loading.


Code Comparison: HTML File to PDF with External Assets

HTMLDOC — HTML File to PDF

using System;
using System.Diagnostics;
using System.IO;

namespace HtmldocFileExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // Assume we have an HTML file: invoice.html
            // CRITICAL: External assets (images, CSS) won't work
            // HTMLDOC does not support:
            // - <link rel="stylesheet" href="styles.css">
            // - <img src="logo.png"> (unless image is base64 embedded)
            // - Modern image formats (WebP, SVG)

            // For HTMLDOC to include images, must use:
            // 1. Absolute file:// URLs, OR
            // 2. base64 data URIs embedded in HTML

            string inputHtmlPath = "invoice.html";
            string outputPdfPath = "invoice.pdf";

            var startInfo = new ProcessStartInfo
            {
                FileName = "htmldoc",
                Arguments = $"--webpage --no-title --no-toc -f \"{outputPdfPath}\" \"{inputHtmlPath}\"",
                RedirectStandardOutput = true,
                RedirectStandardError = true,
                UseShellExecute = false,
                CreateNoWindow = true
            };

            try
            {
                using (var process = Process.Start(startInfo))
                {
                    process.WaitForExit();

                    if (process.ExitCode != 0)
                    {
                        string error = process.StandardError.ReadToEnd();
                        Console.WriteLine($"Error: {error}");
                        return;
                    }
                }

                Console.WriteLine($"PDF generated: {outputPdfPath}");
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error: {ex.Message}");
            }
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

Asset handling checklist for HTMLDOC:

  • ☐ Convert all <img src="relative/path.png"> to <img src="file:///absolute/path.png">
  • ☐ Or embed images as base64 data URIs in HTML
  • ☐ Remove all <link> tags for external CSS (not supported)
  • ☐ Inline all CSS using deprecated style attributes (e.g., <p style="color: red;">)
  • ☐ Verify image formats are supported (PNG, JPEG, GIF only)
  • ☐ No SVG, WebP, or modern image formats

IronPDF — HTML File to PDF

using IronPdf;

namespace IronPdfFileExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // Instantiate renderer
            var renderer = new ChromePdfRenderer();

            // Render HTML file with automatic asset resolution
            var pdf = renderer.RenderHtmlFileAsPdf("invoice.html");

            // IronPDF automatically resolves:
            // <img src="logo.png"> - loads from same directory
            // <link href="styles.css"> - loads and applies CSS
            // <script src="charts.js"> - executes JavaScript
            // All relative paths resolved from HTML file location

            // Save result
            pdf.SaveAs("invoice.pdf");
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

Asset handling checklist for IronPDF:

  • ☑ Relative paths work automatically (images, CSS, JavaScript)
  • ☑ Supports all modern image formats (PNG, JPEG, WebP, SVG, GIF)
  • ☑ External CSS files loaded and applied
  • ☑ JavaScript executes before PDF generation
  • ☑ Web fonts (WOFF/WOFF2) supported
  • ☑ No manual path conversion needed

See the HTML file to PDF guide for details on base path configuration and external resource handling.


Code Comparison: Headers and Footers

HTMLDOC — Headers and Footers

using System;
using System.Diagnostics;
using System.IO;

namespace HtmldocHeaderFooter
{
    class Program
    {
        static void Main(string[] args)
        {
            // HTMLDOC headers/footers are configured via command-line options
            // Limited to simple text strings with tokens
            // Cannot use custom HTML or CSS for styling

            string htmlContent = "<html><body><h1>Report</h1><p>Content...</p></body></html>";
            string tempHtmlPath = Path.Combine(Path.GetTempPath(), "report.html");
            File.WriteAllText(tempHtmlPath, htmlContent);

            string outputPdfPath = "report.pdf";

            // HTMLDOC header/footer options:
            // --header left center right
            // --footer left center right
            // Tokens: / (page number), 1 (total pages), t (title), d (date)
            var startInfo = new ProcessStartInfo
            {
                FileName = "htmldoc",
                Arguments = $"--webpage " +
                           $"--header ... " +     // Left: empty, Center: "Company Report", Right: empty
                           $"--footer .1. " +     // Left: empty, Center: "Page X", Right: empty
                           $"-f \"{outputPdfPath}\" \"{tempHtmlPath}\"",
                RedirectStandardOutput = true,
                RedirectStandardError = true,
                UseShellExecute = false,
                CreateNoWindow = true
            };

            try
            {
                using (var process = Process.Start(startInfo))
                {
                    process.WaitForExit();

                    if (process.ExitCode != 0)
                    {
                        Console.WriteLine($"Error: {process.StandardError.ReadToEnd()}");
                        return;
                    }
                }

                Console.WriteLine($"PDF with headers/footers: {outputPdfPath}");
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error: {ex.Message}");
            }
            finally
            {
                try { File.Delete(tempHtmlPath); } catch { }
            }
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

Header/footer limitation checklist for HTMLDOC:

  • ☐ Text-only headers/footers (no HTML, no images)
  • ☐ Limited tokens (/, 1, t, d - page number, total pages, title, date)
  • ☐ No custom styling or fonts
  • ☐ Fixed three-column layout (left, center, right)
  • ☐ No dynamic content beyond predefined tokens
  • ☐ Cannot vary headers/footers by page

IronPDF — Headers and Footers

using IronPdf;

namespace IronPdfHeaderFooter
{
    class Program
    {
        static void Main(string[] args)
        {
            // Instantiate renderer
            var renderer = new ChromePdfRenderer();

            // Configure HTML header with full CSS support
            renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter
            {
                MaxHeight = 20, // millimeters
                HtmlFragment = @"
                    <div style='text-align:center; font-family: Arial; font-size: 12pt;'>
                        <img src='data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...' height='30'/>
                        <b>Company Report - {date}</b>
                    </div>",
                DrawDividerLine = true
            };

            // Configure HTML footer with page numbers
            renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter
            {
                MaxHeight = 15,
                HtmlFragment = "<center style='font-size: 9pt; color: #666;'>Page {page} of {total-pages}</center>",
                DrawDividerLine = true
            };

            // Set margins
            renderer.RenderingOptions.MarginTop = 25;    // mm
            renderer.RenderingOptions.MarginBottom = 20; // mm

            // Render to PDF
            var pdf = renderer.RenderHtmlAsPdf("<h1>Report</h1><p>Content...</p>");
            pdf.SaveAs("report.pdf");
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

Header/footer capability checklist for IronPDF:

  • ☑ Full HTML/CSS support in headers/footers
  • ☑ Images (base64 or external URLs)
  • ☑ Custom fonts and styling
  • ☑ Dynamic placeholders: {page}, {total-pages}, {date}, {time}, {url}, {html-title}, {pdf-title}
  • ☑ Different headers/footers for first page vs. subsequent pages
  • ☑ Programmatic per-PDF customization

See the headers and footers guide for advanced layout options.


API Mapping Reference

HTMLDOC Concept IronPDF Equivalent
Command-line executable ChromePdfRenderer class
htmldoc --webpage RenderHtmlAsPdf()
--footer options RenderingOptions.HtmlFooter
--header options RenderingOptions.HtmlHeader
/ token (page number) {page} placeholder
1 token (total pages) {total-pages} placeholder
d token (date) {date} placeholder
File-based I/O In-memory processing
Process.Start() Direct library call
Exit code error handling C# exception handling
Platform-specific binary Cross-platform NuGet package

Comprehensive Feature Comparison

Category Feature HTMLDOC IronPDF
Status Active Development Yes (legacy scope) Yes (modern web)
Status Last Release Sept 2025 (1.9.21) Monthly updates
Status Open Source Yes (GPL v2) Commercial
Support Support Model Community (GitHub) 24/5 engineer chat
Support Commercial Support No Yes
Support SLA Available No Yes (premium)
Content Creation HTML Version Supported 3.2 + limited 4.01 HTML5
Content Creation CSS Support No Full CSS3
Content Creation JavaScript Execution No Yes
Content Creation Web Fonts No Yes (WOFF/WOFF2)
Content Creation Modern Image Formats No (PNG/JPEG/GIF only) Yes (WebP, SVG, etc.)
Content Creation Unicode Support Limited (Western only) Full Unicode
Content Creation Forms in HTML No Yes
PDF Operations HTML Headers/Footers Text-only tokens Full HTML/CSS
PDF Operations Merge PDFs No Yes
PDF Operations Split PDFs No Yes
PDF Operations Extract Text No Yes
PDF Operations Watermarks No Yes
PDF Operations Digital Signatures No Yes
PDF Operations Forms (Fill/Flatten) No Yes
Security Encryption Limited Yes (AES-256)
Security Permissions Control Basic Granular
Development Integration Type External process Native .NET library
Development Async/Await Support No (Process.Start) Yes (native async)
Development In-Memory Processing No (file-based I/O) Yes
Development NuGet Package No Yes
Development .NET Framework N/A (external tool) 4.6.2+
Development .NET Core/.NET 5+ N/A (external tool) Yes (6, 8, 9, 10)
Development Cross-Platform Deployment Yes (separate binaries) Yes (single package)
Known Issues Requires External Executable Yes No
Known Issues File-Based I/O Only Yes No
Known Issues Process Management Overhead Yes No
Known Issues CSS Not Supported By design N/A
Known Issues JavaScript Not Supported By design N/A

Decision Checklist: Should You Use HTMLDOC in 2026?

✅ HTMLDOC is appropriate if:

  • ☐ Your HTML is strictly HTML 3.2 era (tables, basic formatting)
  • ☐ You need PostScript or EPUB output (HTMLDOC supports these)
  • ☐ Your content contains NO CSS, NO JavaScript, NO modern HTML5
  • ☐ You're converting legacy documentation or simple reports
  • ☐ You need a free, open-source solution and accept its limitations
  • ☐ Your deployment environment can accommodate external executable dependencies

❌ HTMLDOC is NOT appropriate if:

  • ☑ Your HTML uses CSS for layout or styling
  • ☑ You need JavaScript execution (charts, dynamic content)
  • ☑ You want modern web fonts or Unicode (CJK, emoji, Arabic)
  • ☑ You need PDF forms, watermarks, or digital signatures
  • ☑ You want native .NET library integration (no process spawning)
  • ☑ You need in-memory HTML to PDF conversion (no temp files)
  • ☑ You want async/await patterns for web applications
  • ☑ You need to merge, split, or edit PDFs programmatically

Migration trigger: If you checked any ❌ items, or if you find yourself constantly working around HTMLDOC's limitations (stripping CSS, converting to HTML 3.2, embedding base64 images), migration to a modern library eliminates those workarounds.


Installation Comparison

HTMLDOC Installation

Windows:

# Download htmldoc.exe from GitHub releases:
# https://github.com/michaelrsweet/htmldoc/releases
# Place in system PATH or use full path in code
Enter fullscreen mode Exit fullscreen mode

Linux (Snap):

sudo snap install htmldoc
Enter fullscreen mode Exit fullscreen mode

macOS:

# Download .dmg from GitHub releases
# Or use Homebrew (if available)
Enter fullscreen mode Exit fullscreen mode

Deployment checklist:

  • ☐ Install HTMLDOC binary on all servers (dev, staging, production)
  • ☐ Verify binary is in system PATH or configure full path
  • ☐ Ensure file system permissions for temp files
  • ☐ Handle platform-specific binary names (htmldoc.exe vs htmldoc)
  • ☐ Version control executable or document version requirements
  • ☐ Configure process execution permissions (firewall, antivirus)

IronPDF Installation

# Single NuGet package for all platforms
dotnet add package IronPdf
Enter fullscreen mode Exit fullscreen mode

Namespace imports:

using IronPdf;
Enter fullscreen mode Exit fullscreen mode

Deployment checklist:

  • ☑ Standard NuGet package management (restore packages)
  • ☑ Native libraries auto-extract and load (no manual steps)
  • ☑ Works cross-platform (Windows, Linux, macOS) from same package
  • ☑ No external executables required

Conclusion

HTMLDOC serves a specific niche: converting simple, legacy HTML documentation (HTML 3.2 era) to PDF, PostScript, or EPUB. It's intentionally scoped—the documentation explicitly states it does not support CSS, JavaScript, forms, or full Unicode. For teams with modern HTML content containing CSS layouts, JavaScript charts, web fonts, or responsive design, HTMLDOC cannot process that content.

Migration becomes mandatory when: your HTML uses any CSS for styling or layout, you need JavaScript execution for dynamic content, you want native .NET library integration instead of spawning external processes, you need to avoid file-based I/O and temp file management, or you require PDF editing capabilities (merge, split, watermark, sign).

IronPDF eliminates architectural mismatches by embedding a Chromium rendering engine. It processes modern HTML5, CSS3, JavaScript, web fonts, and Unicode the same way Chrome does. Native .NET library with async/await support, in-memory processing (no temp files), comprehensive PDF manipulation API (merge, split, watermark, encrypt, sign), and 24/5 engineer support. The library runs wherever .NET runs—Windows, Linux, macOS, Docker, serverless—with no external executable dependencies.

Are you still maintaining HTML 3.2 conversion workflows? What's your process for stripping modern CSS and JavaScript before PDF generation?

For modern HTML-to-PDF conversion, explore the HTML to PDF tutorial and PDF editing guide.

Top comments (0)