[//]: #@corifeus-header [](https://www.npmjs.com/package/p3x-html-pdf) [](https://paypal.me/patrikx3) [](https://www.patrikx3.com/en/front/contact) [](https://www.facebook.com/corifeus.software) [](https://stats.uptimerobot.com/9ggnzcWrw) # 📃 Generates PDF from HTML with custom headers and footers with wkhtmltopdf v2025.4.154 🌌 **Bugs are evident™ - MATRIX️** 🚧 **This project is under active development!** 📢 **We welcome your feedback and contributions.** ### NodeJS LTS is supported ### 🛠️ Built on NodeJs version ```txt v22.13.0 ``` # 📝 Description [//]: #@corifeus-header:end **p3x-html-pdf** is a Node.js package that generates PDFs from HTML with custom headers and footers using `wkhtmltopdf`. It is a robust tool for creating professional-grade PDFs with features like: - 📜 **Dynamic Headers and Footers**: Add placeholders for page numbers, dates, and more. - 🛠️ **Customizable Layouts**: Configure margins, orientation, and paper size. - ⚡ **Async/Await Support**: Modern JavaScript compatibility for efficient workflows. - 🔄 **Dynamic Content**: Render data-driven tables and content dynamically. --- ## 🚀 Installation Install via Yarn: ```bash yarn add p3x-html-pdf ``` Or install via npm: ```bash npm install p3x-html-pdf ``` Import in your project: ```javascript const { generate } = require('p3x-html-pdf'); ``` --- ## 📖 Usage Example ```javascript const { generate } = require('p3x-html-pdf'); const path = require('path'); (async () => { const options = { settings: { save: true, template: { format: 'A4', orientation: 'portrait', marginLeft: 10, marginRight: 10, }, html: ` <div id="p3x-header" data-height="20mm"> <h1>Header Content</h1> </div> <div id="p3x-footer" data-height="15mm"> <p>Page \${page} of \${pages}</p> </div> <div> <h2>Content</h2> <p>This is a test PDF document.</p> <table width="100%" align="left" border="1"> <tr> <th align="left">Header 1</th> <th align="left">Header 2</th> <th align="left">Header 3</th> </tr> <tr> <td>Data 1</td> <td>Data 2</td> <td>Data 3</td> </tr> <tr> <td>Data 4</td> <td>Data 5</td> <td>Data 6</td> </tr> </table> </div> `, }, title: 'Sample PDF', saveFile: path.resolve(__dirname, 'output.pdf'), }; try { await generate(options); console.log('✅ PDF generated successfully!'); // or options.save = false const buffer = await generate(options); } catch (err) { console.error('❌ Error generating PDF:', err); } })(); ``` --- ## 🔧 Configuration ### Options - **Settings** - `save`: If false, it returns as a buffer. - `template.format`: Page size, e.g., `A4`, `Letter`. - `template.orientation`: Page orientation (`portrait` or `landscape`). - `template.marginLeft`, `template.marginRight`: Margins in mm. - `template.copies`: Copies to generate. - `template.fixedWidth` and `template.fixedHeight`: If above zero, generates in millimeters. - `html`: HTML content with placeholders. - **title**: PDF document title. - **saveFile**: Path for saving the PDF. - **base** The HTML base href is other then current directory, it can be online as well. - **css**: Customize the CSS for serving, by default it is in `src/html-template.css` - **jquery**: The latest that works with webkit is jQuery v1.12.4 is required, you can extend with more functions, the default is in `src/jquery-1.12.4.min.js` - **javascriptDelay**: The delay before the PDF is generated as default is 1000 ms. For more options, check the official [wkhtmltopdf usage guide](https://wkhtmltopdf.org/usage/wkhtmltopdf.txt). Unfortunately the version latest HTTPS TLS 1.3 is not working, so it is better to use inline filesystem images or using HTTP as that is dated but still works. --- ## 🌟 Placeholders You can use placeholders in your HTML for dynamic data (only these, but it is enough, the rest you can generate in HTML): - `${page}`: Current page. - `${pages}`: Total pages. - `${frompage}`: The starting page of the current section. - `${topage}`: The ending page of the current section. - `${webpage}`: The URL of the web page (if applicable). - `${section}`: The name of the current section. - `${subsection}`: The name of the current subsection. - `${date}`: The current date in a localized format. - `${isodate}`: The current date in ISO 8601 format. - `${time}`: The current time. - `${title}`: The document title. - `${doctitle}`: The title of the document as defined in metadata. - `${sitepage}`: Current site page number (specific context). - `${sitepages}`: Total number of site pages (specific context). ### Example ```html <div id="p3x-footer" data-height="10mm"> <p>Page ${page} of ${pages}</p> </div> ``` The `p3x-footer` and `p3x-header` should not have any styles other than `id` and `data-height`. --- ## 📊 Advanced Features - **Debugging**: Use `debug: true` to enable detailed logs. - **Header/Footer Templates**: Create rich HTML templates for headers/footers. - **Dynamic Content**: Inject dynamic tables, invoices, or other content into the PDF. --- ## 🌟 Headers and Footers in `p3x-html-pdf` This document provides a detailed explanation of how to work with headers and footers using `p3x-html-pdf`, including first-page-specific headers and indexed headers for subsequent pages. With this approach, you can create professional-grade PDFs with precise control over header and footer content. --- ### 📖 Overview Headers and footers in `p3x-html-pdf` are managed via HTML templates. You can: - Define **default headers and footers** for all pages. - Create **specific headers or footers** for certain pages using indexing (e.g., `p3x-header-1` for the first page). - Dynamically calculate content for headers and footers, such as page numbers, document titles, or custom logic. --- ### 🚀 How It Works `p3x-html-pdf` uses the `id` attribute and `data-height` to manage headers and footers. The key attributes and elements are: - **Header IDs**: - `p3x-header`: The default header for all pages. - `p3x-header-<page>`: A header for a specific page (e.g., `p3x-header-1` for the first page). - **Footer IDs**: - `p3x-footer`: The default footer for all pages. - `p3x-footer-<page>`: A footer for a specific page. - **`data-height`**: Specifies the height of the header/footer (in millimeters). Ensure this matches the expected content size to prevent overlap. --- ### 🌟 Example: First Page Header and Default Header The following example demonstrates a **custom header** for the first page and a **default header** for the rest of the document. #### HTML Template ```html <div id="p3x-header-1" data-height="40mm"> <div style="width: 100%; padding: 0px; display: table;"> <div style="display: table-cell; vertical-align: middle;"> <img src="http://cdn.corifeus.com/assets/png/patrikx3.png" alt="Header Logo" style="height:40mm; margin:0;"/> </div> <div style="display: table-cell; vertical-align: middle; text-align: right; width: 100%;"> <h1 style="margin: 0; font-size: 20px; color: #333;">P3X HTML Invoice - First Page</h1> <p style="margin: 5px 0 0; font-size: 14px; color: #555;">Generated: ${new Date().toLocaleDateString()}</p> </div> </div> </div> <div id="p3x-header" data-height="40mm"> <div style="display: table; width: 100%; height: 40mm; text-align: right;"> <div style="display: table-cell; vertical-align: middle; text-align: right;"> <h1 style="margin: 0; font-size: 20px; color: #333;">P3X HTML Invoice</h1> <p style="margin: 5px 0 0; font-size: 14px; color: #555;">Generated: ${new Date().toLocaleDateString()}</p> </div> </div> </div> <div id="p3x-footer" data-height="10mm"> <div style="text-align: right; font-size: 12px; color: #777;"> Page ${page} of ${pages} </div> </div> ``` --- ### 🛠️ Dynamic Header and Footer Logic - Use indexed headers or footers for specific pages. - Utilize placeholders like `${page}` and `${pages}` to dynamically display the current page and total pages. #### Example Configuration in JavaScript ```javascript const options = { settings: { save: true, template: { format: 'A4', marginLeft: 10, marginRight: 10, orientation: 'portrait', }, html: ` <div id="p3x-header-1" data-height="40mm"> <!-- Custom header for the first page --> </div> <div id="p3x-header" data-height="40mm"> <!-- Default header for subsequent pages --> </div> <div id="p3x-footer" data-height="10mm"> <!-- Footer for all pages --> </div> `, }, title: 'Dynamic Headers and Footers Example', saveFile: path.resolve(__dirname, 'output.pdf'), }; ``` --- ### 📏 Calculating Headers and Footers per Page When designing headers and footers: 1. **Estimate Content Size:** - Use `data-height` to reserve enough space for your header or footer content. - Example: A header with a logo and text may need `40mm`. 2. **Adjust Margins:** - Ensure the margins accommodate both the header/footer and the main content. 3. **Testing for Multi-Page Documents:** - For multi-page documents, validate the alignment of headers and footers across all pages. --- #### 📄 Headers and Footers with Indexed Customization `p3x-html-pdf` supports indexed headers and footers, allowing unique designs for specific pages. For example, `p3x-header-1` can define a header for the first page, while `p3x-header` applies to subsequent pages. Similarly, `p3x-footer-1` can be used for a custom first-page footer. ##### Key Points: 1. **Indexed IDs**: Use `p3x-header-1`, `p3x-footer-1`, etc., for specific pages. Default headers (`p3x-header`) and footers (`p3x-footer`) are used when no specific index is found. 2. **Consistent Heights**: All headers and footers must share the same `data-height` (e.g., `40mm` for headers, `10mm` for footers) to ensure proper alignment and accurate page calculations. 3. **Dynamic Content**: Use placeholders like `${page}` and `${pages}` to display page-specific data dynamically. This approach allows tailored styling for specific pages while maintaining consistent layouts throughout the document. --- ### 📊 Advanced Features - Combine **indexed headers/footers** for specific pages with a **default** fallback. - Use JavaScript in the `header-footer.html` template to dynamically adjust content. - Use indexed configurations to simulate "first-page" or "last-page" behavior. --- ### 🖼️ Example Output You can generate a PDF with the provided configuration to see how headers and footers are applied dynamically. For larger documents, this approach allows consistent styling with room for customization. ## 🌍 Architecture `p3x-html-pdf` works seamlessly on Linux, Windows and ARM64. --- ## 🖼️ Example Output Check out an example output PDF: [Example PDF](https://cdn.corifeus.com/git/html-pdf/assets/p3x-html-pdf-output.pdf).  --- ## 🔬 Legacy Rendering with Webkit This library uses `wkhtmltopdf`, which relies on an older version of Webkit. As such, it does not support modern CSS features like `flexbox`. Instead, older solutions such as `float` and `table`-based layouts must be used for alignment. While these approaches are not modern, they are efficient and compatible with the rendering engine. For instance, the following layout works seamlessly: ```html <div id="p3x-header" data-height="40mm"> <div style="width: 100%; padding: 0px; display: table;"> <div style="display: table-cell; vertical-align: middle;"> <img src="http://cdn.corifeus.com/assets/png/patrikx3.png" alt="Header Logo" style="height:40mm; margin:0;"/> </div> <div style="display: table-cell; vertical-align: middle; text-align: right; width: 100%;"> <h1 style="margin: 0; font-size: 20px; color: #333;">P3X HTML Invoice</h1> <p style="margin: 5px 0 0; font-size: 14px; color: #555;">Generated: 2023-10-01</p> </div> </div> </div> ``` ## Steps to Clone and Run `test/test.js` 1. **Clone the Repository**: ```bash git clone https://github.com/patrikx3/html-pdf.git cd html-pdf ``` 2. **Install Dependencies**: Using Yarn: ```bash yarn install ``` Or, using NPM: ```bash npm install ``` 3. **Run the Test Script**: ```bash node ./test/test.js ``` --- ## Puppeteer vs. p3x-html-pdf: Resource Usage and Features Comparison When deciding between **Puppeteer** and **p3x-html-pdf**, it's essential to understand their differences in resource usage and capabilities. ### Technology Difference - **p3x-html-pdf** is built on **wkhtmltopdf**, which uses the WebKit rendering engine. It's lightweight and optimized for HTML-to-PDF tasks. - **Puppeteer** launches a full **Chrome/Chromium** instance, consuming more CPU and memory, even in headless mode. ### Resource Usage Comparison | Feature | p3x-html-pdf (wkhtmltopdf) | Puppeteer (Chrome/Chromium) | |------------------------|---------------------------------------------|------------------------------------------| | **Memory Usage** | Low | High | | **CPU Usage** | Low | High | | **Startup Time** | Fast | Slower due to browser launch | | **Dynamic Content** | Limited support for JavaScript | Full support for JavaScript | | **Rendering Accuracy** | Basic CSS and HTML support | Pixel-perfect rendering with modern web standards | | **Flexibility** | Headers, footers, scripts (older JS versions) | Highly customizable (headers, footers, scripts) | | **Scalability** | Suitable for lightweight tasks and servers | Better for advanced use cases and large-scale rendering | | **File Size** | Smaller binary for wkhtmltopdf dependency | Puppeteer requires downloading Chromium (~100MB) | ### Trade-offs #### p3x-html-pdf (wkhtmltopdf) - **Pros:** - Lightweight and uses fewer resources. - Faster startup time. - Ideal for static HTML content with minimal JavaScript or CSS. - **Cons:** - Limited support for modern web standards and advanced JavaScript. - Basic rendering capabilities. #### Puppeteer - **Pros:** - Full support for dynamic content, advanced JavaScript, and modern web standards. - Highly customizable headers, footers, and PDF options. - Pixel-perfect rendering accuracy. - **Cons:** - Consumes more CPU and memory. - Slower startup time due to launching a full Chrome/Chromium instance. ### When to Use Each #### Use p3x-html-pdf (wkhtmltopdf): - When your content is **static** or doesn’t rely on modern web technologies. - When resource efficiency is a priority (e.g., on resource-constrained servers). #### Use Puppeteer: - When your content is **dynamic** or relies heavily on JavaScript and CSS. - When rendering accuracy, modern web technology support, or customization is critical. ### Conclusion - **p3x-html-pdf** (wkhtmltopdf) is a better fit for lightweight tasks with simple requirements. - **Puppeteer** excels in advanced and dynamic use cases but comes with higher resource costs. --- **Happy PDF Generating!** 🎉 [//]: #@corifeus-footer --- ## 🚀 Quick and Affordable Web Development Services If you want to quickly and affordably develop your next digital project, visit [corifeus.eu](https://corifeus.eu) for expert solutions tailored to your needs. --- ## 🌐 Powerful Online Networking Tool Discover the powerful and free online networking tool at [network.corifeus.com](https://network.corifeus.com). **🆓 Free** Designed for professionals and enthusiasts, this tool provides essential features for network analysis, troubleshooting, and management. Additionally, it offers tools for: - 📡 Monitoring TCP, HTTP, and Ping to ensure optimal network performance and reliability. - 📊 Status page management to track uptime, performance, and incidents in real time with customizable dashboards. All these features are completely free to use. --- ## ❤️ Support Our Open-Source Project If you appreciate our work, consider ⭐ starring this repository or 💰 making a donation to support server maintenance and ongoing development. Your support means the world to us—thank you! --- ### 🌍 About My Domains All my domains, including [patrikx3.com](https://patrikx3.com), [corifeus.eu](https://corifeus.eu), and [corifeus.com](https://corifeus.com), are developed in my spare time. While you may encounter minor errors, the sites are generally stable and fully functional. --- ### 📈 Versioning Policy **Version Structure:** We follow a **Major.Minor.Patch** versioning scheme: - **Major:** 📅 Corresponds to the current year. - **Minor:** 🌓 Set as 4 for releases from January to June, and 10 for July to December. - **Patch:** 🔧 Incremental, updated with each build. **🚨 Important Changes:** Any breaking changes are prominently noted in the readme to keep you informed. --- [**P3X-HTML-PDF**](https://corifeus.com/html-pdf) Build v2025.4.154 [](https://www.npmjs.com/package/p3x-html-pdf) [](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=QZVM4V6HVZJW6) [](https://www.patrikx3.com/en/front/contact) [](https://www.facebook.com/corifeus.software) [//]: #@corifeus-footer:end