md-pdf-studio 2.2.0 → 2.4.0

package/README.md

@@ -8,9 +8,13 @@
 [![npm downloads](https://img.shields.io/npm/d18m/md-pdf-studio)](https://www.npmjs.com/package/md-pdf-studio)
 ![Browser Extension](https://img.shields.io/badge/Extension-Manifest_V3-green)
 ![License](https://img.shields.io/badge/license-MIT-green)
+[![Official vannt-dev build](https://vannt-dev.github.io/badges/official.svg)](https://vannt-dev.github.io/official.html)
 
 ---
 
+Official builds are listed at [vannt-dev.github.io/official.html](https://vannt-dev.github.io/official.html);
+anything else is not published by vannt-dev.
+
 ## ✨ Features
 
 - 🧩 **Browser Extension (Manifest V3)**:
@@ -19,7 +23,9 @@
   - Convert active web page or GitHub raw Markdown files with 1 click.
   - Context menu integration: Right-click selected Markdown text or any page -> "Convert to PDF".
   - Full-page Print Preview with live theme switching, Font Selector, Auto TOC, Custom CSS, and native PDF/HTML export.
-- 📑 **Auto Cover Page Generator**: Generate elegant document report cover pages via YAML Front Matter (`cover: true`) or `--cover` flag.
+  - Page numbers and a running header/footer, set in the popup (off by default).
+- 📑 **Auto Cover Page Generator**: Generate elegant document report cover pages via YAML Front Matter (`cover: true`) or `--cover` flag. The author and date labels are in English, or in Vietnamese with `lang: vi` in the front matter.
+- 🔢 **Page Numbers & Running Header/Footer**: `--page-numbers` prints "Page 3 of 12" at the foot of each page (`--page-numbers simple` prints "3"). `--header "text"` and `--footer "text"` print a line of text at the top and foot of each page, with `{title}`, `{author}`, `{date}`, `{page}` and `{pages}` filled in (`--header "{title}"` prints the document title, `""` prints nothing). Both need their text right after the flag: `md2pdf --header README.md` is refused, because `README.md` is an input file. `--page-numbers` takes `full` or `simple` as its value and nothing else, so `md2pdf --page-numbers README.md` converts `README.md`. With both a footer and page numbers, the footer text sits left and the numbers right. The cover page is printed without them, but counts as page 1. All off by default; front matter keys `header`, `footer` and `pageNumbers` do the same. PDF only (the CLI and the extension); Word and EPUB leave them out.
 - 📌 **Dotted Leader Line Table of Contents (TOC)**: Auto-generates publication-grade TOC with dotted leader lines (`...`) and clickable anchor links (`--toc`).
 - 🎨 **7 Preset Themes**: `modern` (default), `dark`, `academic`, `github`, `ebook`, `cyberpunk`, and `minimal`.
 - 🔤 **Open-Source Font Selector**: 100% free under SIL OFL / Apache 2.0 (`Inter`, `Roboto`, `Lora`, `Merriweather`, `JetBrains Mono`, `Fira Code`).
@@ -30,6 +36,9 @@
 - 🌈 **Syntax Highlighting**: Fenced code blocks that name a language (` ```js `, ` ```python `, ` ```diff `, …) are coloured at build time with highlight.js — no CDN, so it also works offline and in static HTML export. Colours follow the theme's code block background. Works in the CLI and in the extension preview.
 - 📐 **LaTeX Math Support**: Mathematical equations rendered with KaTeX.
 - 📝 **Footnotes**: `text[^1]` with `[^1]: the note` anywhere in the file. Notes are numbered in the order they are first referenced, gathered at the end of the document, and linked both ways. Works in the CLI and in the extension preview.
+- 📘 **Word & EPUB Export (CLI)**: `-f docx` writes a Word document and `-f epub` an EPUB 3 e-book, straight from the Markdown and without a browser. Headings, lists (nested, numbered from any start, task lists), tables with their alignment, code blocks, quotes, footnotes, links and local images become the real thing in each format — Word styles you can restyle, a chapter per top-level heading and a navigation menu in the EPUB. `--toc`, `--cover`, page size, orientation and margins apply to Word; `--toc` and `--cover` to EPUB. Themes, custom CSS, Mermaid diagrams and KaTeX math are for PDF and HTML only: a diagram or formula is kept as its source. An image on the web is not downloaded — it is named in Word and becomes a link in the EPUB — and a link to a neighbouring file keeps its text only.
+- 🔖 **PDF Bookmarks (CLI)**: The PDF gets an outline (bookmarks) built from its headings, nested by level, so a PDF viewer's sidebar can jump to any section. On by default; `--no-outline` or `outline: false` in the front matter leaves it out. The extension prints through the browser's print dialog, which does not add bookmarks.
+- 📎 **File Includes (CLI)**: A line that holds only `@import "chapters/intro.md"` is replaced by that file, relative to the file the line is in. A Markdown file is inserted as Markdown (without its front matter) and may import further files; any other file — `@import "src/app.js"` — is inserted as a code block labelled with its extension. Lines inside a code block are left alone, a missing file or files that import each other stop the conversion with the file and line, and watch mode follows the imported files. `--no-include` turns it off.
 - 💡 **GitHub Callout Box Alerts**: Support for `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, `> [!IMPORTANT]`, and `> [!CAUTION]`.
 - 💻 **ASCII UI Mockups**: Styled dark-theme boxes for terminal output & ASCII wireframe mockups.
 
@@ -83,6 +92,29 @@ npx md-pdf-studio file1.md file2.md -o output_dir/
 
 # Convert entire directory of .md files
 npx md-pdf-studio ./docs/ -o ./dist/
+
+# Word document with a cover page and a table of contents
+npx md-pdf-studio report.md -f docx --cover --toc
+
+# EPUB e-book, one chapter per top-level heading
+npx md-pdf-studio book.md -f epub -o book.epub
+```
+
+A book kept as one file per chapter is one document with includes:
+
+```markdown
+---
+title: Handbook
+toc: true
+---
+# Handbook
+
+@import "chapters/01-intro.md"
+@import "chapters/02-setup.md"
+
+## Example config
+
+@import "examples/config.yml"
 ```
 
 ---
@@ -91,13 +123,16 @@ npx md-pdf-studio ./docs/ -o ./dist/
 
 | Flag | Alias | Description | Default |
 | :--- | :--- | :--- | :--- |
-| `-o, --output <path>`| | Output PDF/HTML file path or target directory | Auto-derived |
-| `-f, --format <format>`| | Output format: `pdf`, `html` | `pdf` |
+| `-o, --output <path>`| | Output file path or target directory | Auto-derived |
+| `-f, --format <format>`| | Output format: `pdf`, `html`, `docx`, `epub` | `pdf` |
 | `-w, --watch` | | Live watch input file and auto-recompile on change | `false` |
 | `-t, --theme <theme>` | | Theme: `modern`, `dark`, `academic`, `github`, `ebook`, `cyberpunk`, `minimal` | `modern` |
 | `--font <font>` | | Font family: `Inter`, `Roboto`, `Lora`, `Merriweather`, `JetBrains Mono`, `Fira Code` | `Inter` |
 | `--cover` | | Auto-generate document report Cover Page | `false` |
 | `--toc` | | Auto-generate Table of Contents with Dotted Leader Lines | `false` |
+| `--page-numbers [style]` | | Page numbers at the foot of each page: `full` ("Page 3 of 12") or `simple` ("3"); any other next argument stays an input | off (`full` when given alone) |
+| `--header <text>` | | Running header; `{title}`, `{author}`, `{date}`, `{page}`, `{pages}` are filled in; `""` for none | off |
+| `--footer <text>` | | Running footer, same placeholders; `""` for none | off |
 | `-p, --page-size <size>`| | Paper size: `A4`, `Letter`, `A3`, `Legal` | `A4` |
 | `-l, --landscape` | | Use landscape page orientation | `false` |
 | `-m, --margin <margin>`| | Custom page margin (e.g. `14mm 12mm 16mm 12mm`) | `14mm 12mm 16mm 12mm` |
@@ -106,6 +141,8 @@ npx md-pdf-studio ./docs/ -o ./dist/
 | `--no-mermaid` | | Disable Mermaid diagram rendering | `false` |
 | `--no-katex` | | Disable KaTeX math formula rendering | `false` |
 | `--no-highlight` | | Disable syntax highlighting of code blocks | `false` |
+| `--no-include` | | Leave `@import "file"` lines as they are instead of inserting the file | `false` |
+| `--no-outline` | | Leave out the PDF bookmarks (outline) made from the headings | `false` |
 
 ---
 
@@ -126,6 +163,13 @@ font: Inter
 pageSize: A4
 landscape: false
 highlight: true
+# document language (default en): cover labels and the page's lang
+lang: en
+# running header and footer; header: true also means the title
+header: "{title}"
+footer: "Engineering Team"
+# full ("Page 3 of 12"), simple ("3") or false
+pageNumbers: full
 ---
 # Document Executive Summary
 ...
@@ -133,13 +177,10 @@ highlight: true
 
 ---
 
-## 🌿 Git Flow & Automated Release Workflow
-
-This project follows standard **Git Flow** branching and automated release publishing:
+## 🌿 Branching & Automated Release Workflow
 
 ### 🔀 Branching Strategy
-- **`main`**: Production-ready branch. Stores stable releases. Pushing a version tag `v*` from `main` triggers a release.
-- **`develop`**: Active development branch. Daily commits, feature additions, and refactoring take place here.
+- **`main`**: The default branch. Changes arrive through pull requests from short-lived feature branches, and pushing a version tag `v*` from `main` triggers a release.
 
 ### 🚀 Automated Release Pipeline
 Whenever a version tag `v*` is pushed, GitHub Actions ([`.github/workflows/release.yml`](.github/workflows/release.yml)) builds from that tag and automatically:
@@ -181,24 +222,32 @@ convert-md-to-pdf/
 │   │   │   ├── cyberpunk.js # Cyberpunk neon dark theme
 │   │   │   └── minimal.js   # Minimal monochrome theme
 │   │   ├── frontmatter.js   # YAML front matter parser
+│   │   ├── include.js       # @import "file" expansion
+│   │   ├── docmodel.js      # Format-neutral document model (blocks of flat runs)
+│   │   ├── docx.js          # Word (.docx) writer
+│   │   ├── epub.js          # EPUB 3 writer
+│   │   ├── images.js        # Local image reading & sizes
+│   │   ├── zip.js           # ZIP container writer for docx/epub
 │   │   ├── cover.js         # Cover page generator
 │   │   ├── toc.js           # Dotted leader line TOC generator
 │   │   ├── sanitizer.js     # HTML sanitizer & escaping
 │   │   ├── utils.js         # Preprocessors & helper re-exports
 │   │   ├── parser.js        # Pipeline parser (Markdown -> HTML)
 │   │   ├── templates.js     # HTML document template builder
+│   │   ├── pagemarks.js     # Page numbers & running header/footer CSS (shared with the extension)
 │   │   └── index.js         # Main library API entrypoint
+│   ├── cli/                 # Command line option checks (options.js)
 │   └── browser/             # Headless browser rendering engine
-│       └── renderer.js      # Puppeteer Chrome/Edge launcher & PDF worker pool
+│       └── renderer.js      # Runs installed Chrome/Edge headless (--print-to-pdf) & PDF worker pool
 ├── extension/               # Browser Extension (Manifest V3)
 │   ├── manifest.json
 │   ├── background/          # Service worker & context menus
 │   ├── content/             # Content script for raw MD pages
 │   ├── popup/               # Extension Popup UI (Batch file, Paste, Page, History)
 │   ├── preview/             # Print Preview & PDF/HTML export page
-│   ├── lib/                 # Vendor libraries (marked, mermaid, katex)
+│   ├── lib/                 # Vendor libraries (marked, mermaid, katex) & code shared with the CLI
 │   └── icons/               # Extension icons (16, 48, 128)
-├── tests/                   # Standalone test suite (7/7 PASS)
+├── tests/                   # Standalone test suite (`npm test`)
 │   └── index.test.js
 ├── dist/                    # Built Chrome Extension zip artifacts
 ├── examples/                # Usage examples & custom CSS templates

package/bin/cli.js

@@ -1,11 +1,17 @@
 #!/usr/bin/env node
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 
 const { Command } = require('commander');
 const path = require('path');
 const fs = require('fs');
 const { convertMarkdownToPdf } = require('../src/core/index');
+const { normalizePageNumbersArgs, parseMarginText } = require('../src/cli/options');
 const packageJson = require('../package.json');
 
+const OUTPUT_FORMATS = ['pdf', 'html', 'docx', 'epub'];
+// An --output that names a file rather than a folder.
+const OUTPUT_FILE = /\.(pdf|html|docx|epub)$/i;
+
 const program = new Command();
 
 program
@@ -14,8 +20,8 @@ program
   .description('High-quality Markdown to PDF converter CLI with Mermaid, Math, TOC, Custom CSS, and Batch conversion.')
   .version(packageJson.version, '-v, --version', 'Output tool version')
   .argument('<inputs...>', 'Input Markdown file(s) or wildcard pattern (.md)')
-  .option('-o, --output <path>', 'Output PDF/HTML file path or destination directory')
-  .option('-f, --format <format>', 'Output format: pdf (default), html', 'pdf')
+  .option('-o, --output <path>', 'Output file path or destination directory')
+  .option('-f, --format <format>', 'Output format: pdf (default), html, docx, epub', 'pdf')
   .option('-w, --watch', 'Watch input file(s) and recompile automatically on changes', false)
   .option('-t, --theme <theme>', 'Theme name: modern (default), dark, academic, minimal, github, ebook, cyberpunk', 'modern')
   .option('--font <font>', 'Font family: Inter (default), Roboto, Lora, Merriweather, JetBrains Mono, Fira Code', 'Inter')
@@ -24,14 +30,22 @@ program
   .option('-l, --landscape', 'Use landscape orientation', false)
   .option('-m, --margin <margin>', 'Page margin (e.g. 14mm 12mm 16mm 12mm)', '14mm 12mm 16mm 12mm')
   .option('--toc', 'Auto-generate Table of Contents (TOC)', false)
+  .option('--page-numbers [style]', 'Print page numbers in the footer: full ("Page 3 of 12", default) or simple ("3")')
+  .option('--header <text>', 'Running header text; {title}, {author}, {date}, {page}, {pages} are filled in ("" for none)', parseMarginText)
+  .option('--footer <text>', 'Running footer text, same placeholders ("" for none)', parseMarginText)
   .option('-c, --css <path>', 'Custom CSS stylesheet file path to inject')
   .option('-k, --keep-html', 'Keep temporary HTML file after conversion', false)
   .option('--no-mermaid', 'Disable Mermaid diagram rendering')
   .option('--no-katex', 'Disable KaTeX math formula rendering')
   .option('--no-highlight', 'Disable syntax highlighting of code blocks')
+  .option('--no-include', 'Leave @import "file" lines as they are instead of inserting the file')
+  .option('--no-outline', 'Leave out the PDF bookmarks (outline) made from the headings')
   .option('-b, --browser <path>', 'Custom Chrome/Edge executable path')
   .action(async (inputArgs, options) => {
     try {
+      // Files pulled in with @import, so watch mode can follow them too.
+      const importedFiles = new Set();
+
       const runConversion = async () => {
         const startTime = Date.now();
         const inputFiles = expandInputFiles(inputArgs);
@@ -43,18 +57,22 @@ program
         }
 
         const targetFormat = (options.format || 'pdf').toLowerCase();
+        if (!OUTPUT_FORMATS.includes(targetFormat)) {
+          throw new Error(`Unknown format "${options.format}". Use one of: ${OUTPUT_FORMATS.join(', ')}`);
+        }
         console.log(`\n\x1b[36m🚀 Converting ${inputFiles.length} file(s) to ${targetFormat.toUpperCase()}...\x1b[0m`);
         console.log(`   Theme:  ${options.theme}`);
         console.log(`   Font:   ${options.font}`);
         console.log(`   Paper:  ${options.pageSize} (${options.landscape ? 'Landscape' : 'Portrait'})`);
         if (options.cover) console.log(`   Cover:  Auto-generated Cover Page Enabled`);
         if (options.toc) console.log(`   TOC:    Auto-generated Table of Contents Enabled`);
+        if (options.pageNumbers) console.log(`   Pages:  Page numbers (${options.pageNumbers === true ? 'full' : options.pageNumbers})`);
         if (options.css) console.log(`   CSS:    ${path.resolve(options.css)}`);
 
         let targetOutputDir = null;
         if (options.output) {
           const resolvedOut = path.resolve(options.output);
-          if (inputFiles.length === 1 && (resolvedOut.endsWith('.pdf') || resolvedOut.endsWith('.html'))) {
+          if (inputFiles.length === 1 && OUTPUT_FILE.test(resolvedOut)) {
             targetOutputDir = null;
           } else {
             targetOutputDir = resolvedOut;
@@ -71,7 +89,7 @@ program
 
           if (targetOutputDir) {
             fileOutPath = path.join(targetOutputDir, `${fileBaseName}.${targetFormat}`);
-          } else if (options.output && (options.output.endsWith('.pdf') || options.output.endsWith('.html'))) {
+          } else if (options.output && OUTPUT_FILE.test(options.output)) {
             fileOutPath = options.output;
           }
 
@@ -86,15 +104,22 @@ program
             margin: options.margin,
             toc: options.toc,
             cover: options.cover,
+            header: options.header,
+            footer: options.footer,
+            pageNumbers: options.pageNumbers,
             cssFile: options.css,
             keepHtml: options.keepHtml,
             mermaid: options.mermaid,
             katex: options.katex,
             highlight: options.highlight,
+            include: options.include,
+            // Only an explicit --no-outline overrides `outline:` in the front matter.
+            outline: options.outline === false ? false : undefined,
             executablePath: options.browser
           });
 
-          const outPathDisplay = result.pdfPath || result.htmlPath;
+          result.includedFiles.forEach(includedFile => importedFiles.add(includedFile));
+          const outPathDisplay = result.outputPath;
           console.log(`   \x1b[32m✔ File saved:\x1b[0m ${outPathDisplay}`);
           count++;
         }
@@ -112,27 +137,35 @@ program
         console.log('\n\x1b[35m👀 Watch mode enabled. Monitoring files for changes...\x1b[0m');
 
         let debounceTimer = null;
+        let watchImports = () => {};
         const triggerRecompile = (filename) => {
           if (debounceTimer) clearTimeout(debounceTimer);
           debounceTimer = setTimeout(async () => {
             console.log(`\n\x1b[33m🔄 Change detected in ${filename}. Recompiling...\x1b[0m`);
             try {
               await runConversion();
+              watchImports();
             } catch (err) {
               console.error(`\x1b[31m✖ Error during watch recompile:\x1b[0m ${err.message}`);
             }
           }, 300);
         };
 
-        inputFiles.forEach(filePath => {
-          if (fs.existsSync(filePath)) {
-            fs.watch(filePath, (eventType) => {
-              if (eventType === 'change') {
-                triggerRecompile(path.basename(filePath));
-              }
-            });
-          }
-        });
+        const watched = new Set();
+        const watchFile = (filePath) => {
+          if (watched.has(filePath) || !fs.existsSync(filePath)) return;
+          watched.add(filePath);
+          fs.watch(filePath, (eventType) => {
+            if (eventType === 'change') {
+              triggerRecompile(path.basename(filePath));
+            }
+          });
+        };
+        // An edit can add an @import, so the list is read again after every run.
+        watchImports = () => importedFiles.forEach(watchFile);
+
+        inputFiles.forEach(watchFile);
+        watchImports();
 
         if (options.css && fs.existsSync(options.css)) {
           fs.watch(options.css, (eventType) => {
@@ -185,4 +218,4 @@ function expandInputFiles(args) {
   return Array.from(filesSet);
 }
 
-program.parse(process.argv);
+program.parse(normalizePageNumbersArgs(process.argv));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "md-pdf-studio",
-  "version": "2.2.0",
-  "description": "A powerful CLI tool and Manifest V3 Browser Extension to convert Markdown files, text, or web pages into beautifully styled PDFs with Mermaid diagrams, LaTeX math, TOC, and themes.",
+  "version": "2.4.0",
+  "description": "A powerful CLI tool and Manifest V3 Browser Extension to convert Markdown files, text, or web pages into beautifully styled PDFs with Mermaid diagrams, LaTeX math, TOC, and themes. The CLI also writes Word (.docx) and EPUB.",
   "main": "src/core/index.js",
   "bin": {
     "md-pdf-studio": "bin/cli.js",
@@ -33,7 +33,9 @@
     "md2pdf",
     "marked",
     "md-pdf-studio",
-    "markdown-to-pdf"
+    "markdown-to-pdf",
+    "docx",
+    "epub"
   ],
   "author": "vannt-dev",
   "license": "MIT",
@@ -57,6 +59,6 @@
     "@commitlint/cli": "^21.2.3",
     "@commitlint/config-conventional": "^21.2.3",
     "adm-zip": "^0.6.0",
-    "lefthook": "^2.1.14"
+    "lefthook": "^2.2.1"
   }
 }

package/src/browser/renderer.js

@@ -1,3 +1,4 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
@@ -48,6 +49,29 @@ function findBrowserExecutable() {
   return null;
 }
 
+/**
+ * The command line that prints a page to PDF with headless Chrome/Edge.
+ * @param {string} fileUrl Page to print
+ * @param {string} outputPath PDF to write
+ * @param {Object} [options]
+ * @param {boolean} [options.legacyHeadless] Use `--headless` for browsers without `--headless=new`
+ * @param {boolean} [options.outline] Add PDF bookmarks from the headings (default true)
+ * @returns {string[]}
+ */
+function buildBrowserArgs(fileUrl, outputPath, options = {}) {
+  return [
+    options.legacyHeadless ? '--headless' : '--headless=new',
+    '--disable-gpu',
+    '--no-sandbox',
+    '--no-pdf-header-footer',
+    // Bookmarks from h1-h6. A browser that does not know the switch ignores it.
+    ...(options.outline === false ? [] : ['--generate-pdf-document-outline']),
+    '--virtual-time-budget=8000',
+    `--print-to-pdf=${outputPath}`,
+    fileUrl
+  ];
+}
+
 /**
  * Renders HTML file to PDF using headless browser
  * @param {string} htmlPath 
@@ -64,28 +88,12 @@ function renderHtmlToPdf(htmlPath, outputPath, options = {}) {
     }
 
     const fileUrl = 'file:///' + path.resolve(htmlPath).replace(/\\/g, '/');
-    const args = [
-      '--headless=new',
-      '--disable-gpu',
-      '--no-sandbox',
-      '--no-pdf-header-footer',
-      '--virtual-time-budget=8000',
-      `--print-to-pdf=${outputPath}`,
-      fileUrl
-    ];
+    const args = buildBrowserArgs(fileUrl, outputPath, { outline: options.outline });
 
     execFile(browserPath, args, { timeout: 30000 }, (error) => {
       if (error) {
         // Fallback for older chrome versions that don't support --headless=new
-        const fallbackArgs = [
-          '--headless',
-          '--disable-gpu',
-          '--no-sandbox',
-          '--no-pdf-header-footer',
-          '--virtual-time-budget=8000',
-          `--print-to-pdf=${outputPath}`,
-          fileUrl
-        ];
+        const fallbackArgs = buildBrowserArgs(fileUrl, outputPath, { outline: options.outline, legacyHeadless: true });
 
         execFile(browserPath, fallbackArgs, { timeout: 30000 }, (err2) => {
           if (err2) {
@@ -135,6 +143,7 @@ async function renderBatchHtmlToPdf(itemPairs, options = {}) {
 }
 
 module.exports = {
+  buildBrowserArgs,
   findBrowserExecutable,
   renderHtmlToPdf,
   renderBatchHtmlToPdf

package/src/cli/options.js

@@ -0,0 +1,61 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
+/**
+ * Command line helpers for options whose value could be mistaken for an input file.
+ */
+const fs = require('fs');
+const { InvalidArgumentError } = require('commander');
+
+const PAGE_NUMBER_STYLES = ['full', 'simple'];
+const INPUT_FILE = /\.(md|markdown|txt)$/i;
+
+/**
+ * `--page-numbers` takes an optional style. Only a known style is read as its value, so in
+ * `--page-numbers README.md` the file stays an input: the flag is given its default instead.
+ * @param {string[]} argv process.argv
+ * @returns {string[]}
+ */
+function normalizePageNumbersArgs(argv) {
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--') {
+      out.push(...argv.slice(i));
+      break;
+    }
+    if (arg === '--page-numbers') {
+      const next = argv[i + 1];
+      if (next !== undefined && PAGE_NUMBER_STYLES.includes(next.toLowerCase())) {
+        out.push(`--page-numbers=${next.toLowerCase()}`);
+        i++;
+      } else {
+        out.push('--page-numbers=full');
+      }
+      continue;
+    }
+    out.push(arg);
+  }
+  return out;
+}
+
+/**
+ * Value check for `--header <text>` and `--footer <text>`. An empty string turns them off.
+ * A value that names an existing Markdown file is refused: it is almost always an input file
+ * that followed the flag, as in `md2pdf --header README.md`.
+ * @param {string} value
+ * @returns {string}
+ */
+function parseMarginText(value) {
+  if (INPUT_FILE.test(value) && fs.existsSync(value) && fs.statSync(value).isFile()) {
+    throw new InvalidArgumentError(
+      `"${value}" is an input file, not header/footer text. Give the text right after the flag, ` +
+        `e.g. --header "{title}" ${value}`
+    );
+  }
+  return value;
+}
+
+module.exports = {
+  PAGE_NUMBER_STYLES,
+  normalizePageNumbersArgs,
+  parseMarginText
+};

package/src/core/cover.js

@@ -1,15 +1,32 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 /**
  * Cover Page Generator Utility
  */
 const { escapeHtml } = require('./sanitizer');
 
+// Cover labels by document language (front matter `lang`); any other language gets English.
+const COVER_LABELS = {
+  en: { author: 'Author', date: 'Date' },
+  vi: { author: 'Tác giả', date: 'Ngày lập' }
+};
+
+/**
+ * The cover labels for a language tag such as `en`, `vi` or `vi-VN`.
+ * @param {string} [language]
+ * @returns {{ author: string, date: string }}
+ */
+function coverLabels(language) {
+  const primary = String(language || 'en').toLowerCase().split(/[-_]/)[0];
+  return COVER_LABELS[primary] || COVER_LABELS.en;
+}
+
 /**
  * Generates a Cover Page HTML block if requested in front matter or options
  * @param {Object} metadata 
  * @returns {string} Cover page HTML string
  */
 function generateCoverPage(metadata = {}) {
-  const { title, subtitle, author, date, cover } = metadata;
+  const { title, subtitle, author, date, cover, language } = metadata;
   
   if (!cover && !subtitle && !author && !date) {
     return '';
@@ -19,6 +36,7 @@ function generateCoverPage(metadata = {}) {
   const docSubtitle = subtitle || '';
   const docAuthor = author || '';
   const docDate = date || '';
+  const labels = coverLabels(language);
 
   return `<div class="cover-page">
   <div class="cover-page-inner">
@@ -27,14 +45,14 @@ function generateCoverPage(metadata = {}) {
     ${docSubtitle ? `<h2 class="cover-subtitle">${escapeHtml(docSubtitle)}</h2>` : ''}
     <div class="cover-divider"></div>
     <div class="cover-meta-container">
-      ${docAuthor ? `<div class="cover-meta-item"><span class="cover-meta-label">Tác giả:</span> <span class="cover-meta-val">${escapeHtml(docAuthor)}</span></div>` : ''}
-      ${docDate ? `<div class="cover-meta-item"><span class="cover-meta-label">Ngày lập:</span> <span class="cover-meta-val">${escapeHtml(docDate)}</span></div>` : ''}
+      ${docAuthor ? `<div class="cover-meta-item"><span class="cover-meta-label">${labels.author}:</span> <span class="cover-meta-val">${escapeHtml(docAuthor)}</span></div>` : ''}
+      ${docDate ? `<div class="cover-meta-item"><span class="cover-meta-label">${labels.date}:</span> <span class="cover-meta-val">${escapeHtml(docDate)}</span></div>` : ''}
     </div>
   </div>
-</div>
-<div class="page-break"></div>\n`;
+</div>\n`;
 }
 
 module.exports = {
+  coverLabels,
   generateCoverPage
 };