chore: release v2.5.0

Author: hajareshyam

.gitignore

@@ -1,5 +1,4 @@
 node_modules/
-.package-lock.json
 dist/
 example/output.pdf
 

CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [2.5.0] — 2026-04-03
+
+### Added
+
+- **`pdfChrome`** on `PdfCreateOptions`: structured **layout** (format, orientation, size, border), **header** (`html` or escaped `title`), **footer** (`html` or `copyright` + optional page numbers via `showPageNumbers`). Merged into html-pdf options; explicit `format` / `header` / `footer` on the same object override.
+- Exported **`buildPdfChrome()`** for building partial html-pdf options from `PdfChromeOptions`.
+- Types: `PdfChromeOptions`, `PdfLayout`, `PdfHeaderConfig`, `PdfFooterConfig`.
+
+### Changed
+
+- **Repository:** removed root `yarn.lock` so installs match **npm** only (aligned with `npm ci` in CI). Keep `package-lock.json` as the lockfile.
+- **`.gitignore`:** dropped the `.package-lock.json` ignore rule (misleading; `package-lock.json` remains tracked).
+
+### Documentation
+
+- **Example (`example/`):** sample uses **`pdfChrome`** (layout, header title, footer copyright + page numbers).
+- **GitHub Pages (`docs/`):** “Layout & header/footer” section, quick start uses `pdfChrome`, install command `npm i pdf-creator-node`, hero link to full readme.
+
 ## [2.4.0] — 2026-04-03
 
 ### Added

docs/assets/css/style.css

@@ -283,6 +283,18 @@ html[data-theme="light"] .theme-toggle__icon--moon {
   font-weight: 600;
 }
 
+.hero__hint {
+  margin: 1rem 0 0;
+  font-size: 0.95rem;
+  line-height: 1.55;
+  color: var(--muted);
+  max-width: 40rem;
+}
+
+.hero__hint code {
+  font-size: 0.88em;
+}
+
 .badges {
   display: flex;
   flex-wrap: wrap;

docs/index.html

@@ -33,6 +33,7 @@
         <nav class="site-nav" aria-label="On this page">
           <a href="#quick-start">Quick start</a>
           <a href="#guide">Guide</a>
+          <a href="#pdf-chrome">Layout &amp; header/footer</a>
           <a href="#ifcond">ifCond</a>
         </nav>
         <div class="site-header__actions">
@@ -99,9 +100,14 @@ <h1>pdf-creator-node</h1>
               >Source on GitHub</a
             >
           </div>
-          <div class="install-block" tabindex="-1">
-            npm i pdf-creator-node --save
-          </div>
+          <div class="install-block" tabindex="-1">npm i pdf-creator-node</div>
+          <p class="hero__hint">
+            Node 18+ · See
+            <a href="https://github.com/hajareshyam/pdf-creator-node/blob/master/readme.md"
+              >full readme on GitHub</a
+            >
+            for TypeScript, validation, and <code>handlebarsHelpers</code>.
+          </p>
         </header>
 
         <section id="quick-start" class="section" aria-labelledby="quick-start-heading">
@@ -118,9 +124,11 @@ <h2 id="quick-start-heading">Quick start</h2>
 var html = fs.readFileSync("template.html", "utf8");
 
 var options = {
-  format: "A3",
-  orientation: "portrait",
-  border: "10mm",
+  pdfChrome: {
+    layout: { format: "A3", orientation: "portrait", border: "10mm" },
+    header: { title: "My report" },
+    footer: { copyright: "© 2026", showPageNumbers: true },
+  },
 };
 
 var document = {
@@ -146,7 +154,7 @@ <h2 id="guide-heading">Step-by-step</h2>
           <ol class="steps">
             <li class="steps__item">
               <div class="steps__title">Install</div>
-              <div class="install-block">npm i pdf-creator-node --save</div>
+              <div class="install-block">npm i pdf-creator-node</div>
             </li>
             <li class="steps__item">
               <div class="steps__title">Load the package and read your template</div>
@@ -216,6 +224,42 @@ <h2 id="guide-heading">Step-by-step</h2>
           </ol>
         </section>
 
+        <section id="pdf-chrome" class="section" aria-labelledby="pdf-chrome-heading">
+          <div class="section__head">
+            <h2 id="pdf-chrome-heading">Layout, header, footer, copyright</h2>
+            <p class="section__lede">
+              Use <code>pdfChrome</code> on the second argument for paper size, repeating
+              header (<code>title</code> or <code>html</code>), and footer with optional
+              <code>copyright</code> and page numbers (<code>{{page}}</code> /
+              <code>{{pages}}</code>). Plain strings are HTML-escaped. Direct
+              <code>format</code> / <code>header</code> / <code>footer</code> on the same
+              object override <code>pdfChrome</code>.
+            </p>
+          </div>
+          <pre class="code-block"><code>var options = {
+  pdfChrome: {
+    layout: {
+      format: "A4",
+      orientation: "portrait",
+      border: "12mm",
+    },
+    header: { title: "Quarterly report" },
+    footer: {
+      copyright: "© 2026 My Company",
+      showPageNumbers: true,
+    },
+  },
+};
+
+pdf.create(document, options);</code></pre>
+          <p class="steps__text">
+            For full control, pass <code>header</code>, <code>footer</code>, and
+            <code>format</code> in the same options object as
+            <a href="https://www.npmjs.com/package/html-pdf">html-pdf</a> expects (see
+            readme).
+          </p>
+        </section>
+
         <section id="ifcond" class="section" aria-labelledby="ifcond-heading">
           <div class="section__head">
             <h2 id="ifcond-heading"><code>ifCond</code> helper</h2>
@@ -234,8 +278,12 @@ <h2 id="ifcond-heading"><code>ifCond</code> helper</h2>
   …
 {{/ifCond}}</code></pre>
           <aside class="note" role="note">
-            <strong>Note:</strong> License terms live in the repository (see
-            footer). Read the full readme on GitHub for more examples.
+            <strong>Note:</strong> See the
+            <a href="https://github.com/hajareshyam/pdf-creator-node/blob/master/readme.md"
+              >readme</a
+            >
+            for validation messages, TypeScript, and optional
+            <code>handlebarsHelpers</code>.
           </aside>
         </section>
 

example/index.js

@@ -1,45 +1,47 @@
 var pdf = require("pdf-creator-node");
-// var pdf = require("../index");
 var fs = require("fs");
 var path = require("path");
-// Read HTML Template
+
 var html = fs.readFileSync(path.join(__dirname, "./template.html"), "utf8");
 
+/**
+ * Options use pdfChrome for layout + repeating header/footer (copyright + page numbers).
+ * You can still set format/header/footer directly on options — they override pdfChrome.
+ */
 var options = {
-  format: "A3",
-  orientation: "portrait",
-  border: "10mm",
+  pdfChrome: {
+    layout: {
+      format: "A3",
+      orientation: "portrait",
+      border: "10mm",
+    },
+    header: { title: "User list" },
+    footer: {
+      copyright: "© pdf-creator-node example",
+      showPageNumbers: true,
+    },
+  },
 };
 
 var users = [
-  {
-    name: "Shyam",
-    age: "26",
-  },
-  {
-    name: "Navjot",
-    age: "26",
-  },
-  {
-    name: "Vitthal",
-    age: "26",
-  },
+  { name: "Shyam", age: "26" },
+  { name: "Navjot", age: "26" },
+  { name: "Vitthal", age: "26" },
 ];
-// By default a file is created but you could switch between Buffer and Streams by using "buffer" or "stream" respectively.
+
+// Default is file output. Use type: "buffer" | "stream" for in-memory output.
 var document = {
   html: html,
-  data: {
-    users,
-  },
+  data: { users },
   path: "./output.pdf",
-  type: "", // "stream" || "buffer" || "" ("" defaults to pdf)
+  type: "",
 };
 
 pdf
   .create(document, options)
-  .then((res) => {
+  .then(function (res) {
     console.log(res);
   })
-  .catch((error) => {
+  .catch(function (error) {
     console.error(error);
   });

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "pdf-creator-node",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "node pdf creator",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package.json

@@ -63,6 +63,28 @@ await pdf.create(document, options);
 - **Buffer:** `type: "buffer"`.
 - **Stream:** `type: "stream"`.
 
+### Layout, header, footer, and copyright (`pdfChrome`)
+
+Use **`pdfChrome`** on the second argument for common paper layout and repeating header/footer without hand-writing `html-pdf` structures. Plain `title` / `copyright` strings are HTML-escaped.
+
+- **`layout`:** `format`, `orientation`, `width`, `height`, `border` (same meaning as [html-pdf](https://www.npmjs.com/package/html-pdf) / Phantom paper size).
+- **`header`:** `html` (raw HTML per page) **or** `title` (centered text). Default height `45mm` when content is set.
+- **`footer`:** `html` **or** combine **`copyright`** with optional **`showPageNumbers`** (`{{page}}` / `{{pages}}`). With `copyright` only, page numbers default **on** unless you set `showPageNumbers: false`. For **page numbers only**, set `showPageNumbers: true` and omit `copyright`. Default footer height `28mm` when content is set.
+
+Anything you set directly on the options object (`format`, `header`, `footer`, …) **overrides** the matching field from `pdfChrome`.
+
+```javascript
+pdf.create(document, {
+  pdfChrome: {
+    layout: { format: "A4", orientation: "portrait", border: "12mm" },
+    header: { title: "Quarterly report" },
+    footer: { copyright: "© 2026 My Company", showPageNumbers: true },
+  },
+});
+```
+
+Advanced: `buildPdfChrome(pdfChrome)` returns partial html-pdf options if you want to compose manually (also exported from the package).
+
 ### Optional Handlebars helpers
 
 Pass `handlebarsHelpers` on the **second** argument (alongside `html-pdf` options). Helpers apply only to that render (isolated Handlebars instance). Built-in `ifCond` is always registered.

readme.md

@@ -1,16 +1,11 @@
 import Handlebars from "handlebars";
 import pdf from "html-pdf";
-import type { CreateOptions } from "html-pdf";
 import type { FileInfo } from "html-pdf";
+import { mergePdfCreateOptions } from "./pdfChrome";
 import { registerHandlebarsHelpers } from "./registerHandlebarsHelpers";
 import type { PdfCreateOptions, PdfDocument } from "./types";
 import { validatePdfDocument } from "./validation";
 
-function stripHtmlPdfOptions(options: PdfCreateOptions): CreateOptions {
-  const { handlebarsHelpers: _h, ...rest } = options;
-  return rest;
-}
-
 function renderHtml(document: PdfDocument, options: PdfCreateOptions): string {
   const hb = Handlebars.create();
   registerHandlebarsHelpers(hb);
@@ -50,7 +45,7 @@ export function create(
       return;
     }
 
-    const pdfOptions = stripHtmlPdfOptions(options);
+    const pdfOptions = mergePdfCreateOptions(options);
     const pdfPromise = pdf.create(html, pdfOptions);
 
     switch (document.type) {

src/createPdf.ts

@@ -8,14 +8,19 @@ import { create } from "./createPdf";
 registerHandlebarsHelpers();
 
 export { create };
+export { buildPdfChrome } from "./pdfChrome";
 export type {
   Document,
   IfCondOptions,
+  PdfChromeOptions,
   PdfCreateOptions,
   PdfDocument,
   PdfDocumentBuffer,
   PdfDocumentFile,
   PdfDocumentStream,
+  PdfFooterConfig,
+  PdfHeaderConfig,
+  PdfLayout,
 } from "./types";
 
 const api = { create };