md-pdf-studio 1.1.0

package/README.md

@@ -0,0 +1,208 @@
+# 📄 convert-md-to-pdf
+
+> A powerful CLI tool and **Browser Extension (Manifest V3)** to convert Markdown (`.md`) files, raw text, or web pages into beautifully styled, high-quality PDF & static HTML documents. Built with support for **Cover Pages**, **Dotted Leader Line Table of Contents (TOC)**, **Mermaid.js diagrams**, **LaTeX Math**, **GitHub Callout Alerts**, **Custom CSS Injection**, **7 Preset Themes**, and **Open-Source Font Selection**.
+
+[![Chrome Web Store](https://img.shields.io/badge/Chrome_Web_Store-Install_Extension-4285F4?logo=googlechrome&logoColor=white)](https://chromewebstore.google.com/detail/markdown-to-pdf-converter/djikikejkmkklfeklfmddaadilhahamj)
+[![Chrome Web Store users](https://img.shields.io/chrome-web-store/users/djikikejkmkklfeklfmddaadilhahamj?label=Chrome%20users)](https://chromewebstore.google.com/detail/markdown-to-pdf-converter/djikikejkmkklfeklfmddaadilhahamj)
+[![npm version](https://img.shields.io/npm/v/md-pdf-studio?color=blue)](https://www.npmjs.com/package/md-pdf-studio)
+[![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)
+
+---
+
+## ✨ Features
+
+- 🧩 **Browser Extension (Manifest V3)**:
+  - Drag & drop single or **multiple `.md` files** directly into the popup.
+  - Auto-saved draft text in popup & conversion history list with 1-click re-open.
+  - 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.
+- 📌 **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`).
+- ⚡ **Live Watch Mode & HTML Export**: Real-time auto-recompilation on file changes (`-w, --watch`) and direct static HTML export (`-f, --format html`).
+- 🚀 **CLI & Batch Conversion**: Convert single files or batch process directories with wildcard patterns.
+- 🎨 **Custom CSS Injection**: Inject custom branding CSS stylesheets (`-c, --css custom.css`).
+- 📊 **Mermaid Diagrams**: Sequence diagrams (with auto note wrapping), flowcharts, class diagrams, and gantt charts.
+- 📐 **LaTeX Math Support**: Mathematical equations rendered with KaTeX.
+- 💡 **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.
+
+---
+
+## 🌐 Extension Installation & Usage
+
+### 🛒 Direct Install from Chrome Web Store (Recommended)
+You can install the official published extension directly with 1-click:
+👉 **[Install Markdown to PDF Converter on Chrome Web Store](https://chromewebstore.google.com/detail/markdown-to-pdf-converter/djikikejkmkklfeklfmddaadilhahamj)**
+
+### 🛠️ Developer Unpacked Installation (Local Build):
+1. Clone or download this repository:
+   ```bash
+   git clone https://github.com/vannt-dev/convert-md-to-pdf.git
+   ```
+2. Open your browser and navigate to `chrome://extensions` (or `edge://extensions`).
+3. Enable **Developer mode** (toggle in the top-right corner).
+4. Click **Load unpacked** (Tải tiện ích đã giải nén).
+5. Select the **`extension`** directory inside this repository (or load `dist/extension-latest.zip`).
+6. The **Markdown to PDF Converter** icon will appear in your browser toolbar!
+
+---
+
+## 💻 CLI Installation & Usage
+
+### Global Installation via npm / npx
+The CLI is published on npm as [`md-pdf-studio`](https://www.npmjs.com/package/md-pdf-studio):
+```bash
+npm install -g md-pdf-studio
+```
+or run directly with `npx`:
+```bash
+npx md-pdf-studio input.md
+```
+A global install provides the `md-pdf-studio` command and the `md2pdf` and `convert-md-to-pdf` aliases.
+PDF output uses a locally installed Google Chrome, Microsoft Edge or Chromium.
+
+> The npm package named `convert-md-to-pdf` is an unrelated project; install `md-pdf-studio` for this tool.
+
+### CLI Examples:
+```bash
+# Convert a Markdown file with Cover Page, Auto TOC & Cyberpunk Theme
+npx md-pdf-studio input.md --cover --toc -t cyberpunk --font "Fira Code" -o output.pdf
+
+# Watch file and auto-recompile on save
+npx md-pdf-studio input.md -w -f html
+
+# Batch convert multiple files to an output directory
+npx md-pdf-studio file1.md file2.md -o output_dir/
+
+# Convert entire directory of .md files
+npx md-pdf-studio ./docs/ -o ./dist/
+```
+
+---
+
+## 🛠️ CLI Options
+
+| 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` |
+| `-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` |
+| `-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` |
+| `-c, --css <path>` | | Custom CSS stylesheet file path to inject | |
+| `-k, --keep-html` | | Keep temporary HTML file after conversion | `false` |
+| `--no-mermaid` | | Disable Mermaid diagram rendering | `false` |
+| `--no-katex` | | Disable KaTeX math formula rendering | `false` |
+
+---
+
+## 📄 Front Matter Options
+
+You can specify conversion settings directly inside your `.md` files using YAML Front Matter:
+
+```yaml
+---
+title: "Quarterly Financial Report"
+subtitle: "Q3 Fiscal Summary"
+author: "Engineering Team"
+date: "2026-08-11"
+cover: true
+toc: true
+theme: github
+font: Inter
+pageSize: A4
+landscape: false
+---
+# Document Executive Summary
+...
+```
+
+---
+
+## 🌿 Git Flow & Automated Release Workflow
+
+This project follows standard **Git Flow** branching and automated release publishing:
+
+### 🔀 Branching Strategy
+- **`main`**: Production-ready branch. Stores stable releases. Merging code into `main` automatically triggers a GitHub Release.
+- **`develop`**: Active development branch. Daily commits, feature additions, and refactoring take place here.
+
+### 🚀 Automated Release Pipeline
+Whenever code is merged from `develop` into `main` (or a version tag `v*` is pushed), GitHub Actions ([`.github/workflows/release.yml`](.github/workflows/release.yml)) automatically:
+1. Runs full unit test suite (`npm test`).
+2. Bundles cross-platform extension zip artifacts (`dist/extension-vX.Y.Z.zip`).
+3. Auto-generates release notes from commit history.
+4. Publishes a new official **[GitHub Release](https://github.com/vannt-dev/convert-md-to-pdf/releases)** with downloadable ZIP binaries attached!
+
+### 💡 1-Click CLI Release Command
+You can also bump version and trigger a release with a single CLI command:
+```bash
+npm run release <version|patch|minor|major>
+# Example: npm run release 1.2.0
+```
+
+Please review our [Git Commit & Push Workflow Guide (GIT_WORKFLOW.md)](GIT_WORKFLOW.md) for conventional commit guidelines and pre-commit checks.
+
+---
+
+## 📁 Project Architecture
+
+```
+convert-md-to-pdf/
+├── bin/
+│   └── cli.js               # CLI executable with watch & format options
+├── src/
+│   ├── core/                # Shared modular conversion engine
+│   │   ├── themes/          # Modular Theme CSS collection
+│   │   │   ├── index.js     # Theme registry & font override builder
+│   │   │   ├── cover.js     # Cover page CSS
+│   │   │   ├── modern.js    # Modern blue theme
+│   │   │   ├── dark.js      # Dark slate theme
+│   │   │   ├── academic.js  # Academic serif theme
+│   │   │   ├── github.js    # GitHub light theme
+│   │   │   ├── ebook.js     # E-Book paper theme
+│   │   │   ├── cyberpunk.js # Cyberpunk neon dark theme
+│   │   │   └── minimal.js   # Minimal monochrome theme
+│   │   ├── frontmatter.js   # YAML front matter parser
+│   │   ├── 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
+│   │   └── index.js         # Main library API entrypoint
+│   └── browser/             # Headless browser rendering engine
+│       └── renderer.js      # Puppeteer Chrome/Edge launcher & 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)
+│   └── icons/               # Extension icons (16, 48, 128)
+├── tests/                   # Standalone test suite (7/7 PASS)
+│   └── index.test.js
+├── dist/                    # Built Chrome Extension zip artifacts
+├── examples/                # Usage examples & custom CSS templates
+├── package.json
+├── README.md
+├── PRIVACY_POLICY.md
+└── GIT_WORKFLOW.md
+```
+
+---
+
+## 📝 License
+
+Distributed under the MIT License. See [LICENSE](LICENSE) for details.

package/bin/cli.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const path = require('path');
+const fs = require('fs');
+const { convertMarkdownToPdf } = require('../src/core/index');
+const packageJson = require('../package.json');
+
+const program = new Command();
+
+program
+  .name('md-pdf-studio')
+  .alias('md2pdf')
+  .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('-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')
+  .option('--cover', 'Auto-generate elegant document Cover Page', false)
+  .option('-p, --page-size <size>', 'Paper size: A4, Letter, A3, Legal', 'A4')
+  .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('-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('-b, --browser <path>', 'Custom Chrome/Edge executable path')
+  .action(async (inputArgs, options) => {
+    try {
+      const runConversion = async () => {
+        const startTime = Date.now();
+        const inputFiles = expandInputFiles(inputArgs);
+
+        if (inputFiles.length === 0) {
+          console.error('\x1b[31m✖ Error:\x1b[0m No valid Markdown files found matching input.');
+          if (!options.watch) process.exit(1);
+          return;
+        }
+
+        const targetFormat = (options.format || 'pdf').toLowerCase();
+        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.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'))) {
+            targetOutputDir = null;
+          } else {
+            targetOutputDir = resolvedOut;
+            if (!fs.existsSync(targetOutputDir)) {
+              fs.mkdirSync(targetOutputDir, { recursive: true });
+            }
+          }
+        }
+
+        let count = 0;
+        for (const file of inputFiles) {
+          const fileBaseName = path.parse(file).name;
+          let fileOutPath = null;
+
+          if (targetOutputDir) {
+            fileOutPath = path.join(targetOutputDir, `${fileBaseName}.${targetFormat}`);
+          } else if (options.output && (options.output.endsWith('.pdf') || options.output.endsWith('.html'))) {
+            fileOutPath = options.output;
+          }
+
+          console.log(`[\x1b[33m${count + 1}/${inputFiles.length}\x1b[0m] Processing: ${file}`);
+
+          const result = await convertMarkdownToPdf(file, fileOutPath, {
+            format: targetFormat,
+            theme: options.theme,
+            font: options.font,
+            pageSize: options.pageSize,
+            orientation: options.landscape ? 'landscape' : 'portrait',
+            margin: options.margin,
+            toc: options.toc,
+            cover: options.cover,
+            cssFile: options.css,
+            keepHtml: options.keepHtml,
+            mermaid: options.mermaid,
+            katex: options.katex,
+            executablePath: options.browser
+          });
+
+          const outPathDisplay = result.pdfPath || result.htmlPath;
+          console.log(`   \x1b[32m✔ File saved:\x1b[0m ${outPathDisplay}`);
+          count++;
+        }
+
+        const duration = ((Date.now() - startTime) / 1000).toFixed(2);
+        console.log(`\x1b[32m✨ Conversion complete!\x1b[0m ${count} file(s) generated in ${duration}s.`);
+      };
+
+      // Initial conversion
+      await runConversion();
+
+      // Watch mode implementation
+      if (options.watch) {
+        const inputFiles = expandInputFiles(inputArgs);
+        console.log('\n\x1b[35m👀 Watch mode enabled. Monitoring files for changes...\x1b[0m');
+
+        let debounceTimer = null;
+        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();
+            } 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));
+              }
+            });
+          }
+        });
+
+        if (options.css && fs.existsSync(options.css)) {
+          fs.watch(options.css, (eventType) => {
+            if (eventType === 'change') {
+              triggerRecompile(path.basename(options.css));
+            }
+          });
+        }
+      }
+    } catch (err) {
+      console.error(`\x1b[31m✖ Error:\x1b[0m ${err.message}`);
+      process.exit(1);
+    }
+  });
+
+function expandInputFiles(args) {
+  const filesSet = new Set();
+
+  args.forEach(arg => {
+    // Check if direct file exists
+    if (fs.existsSync(arg)) {
+      const stat = fs.statSync(arg);
+      if (stat.isFile() && (arg.endsWith('.md') || arg.endsWith('.markdown') || arg.endsWith('.txt'))) {
+        filesSet.add(path.resolve(arg));
+      } else if (stat.isDirectory()) {
+        const dirFiles = fs.readdirSync(arg);
+        dirFiles.forEach(f => {
+          if (f.endsWith('.md') || f.endsWith('.markdown')) {
+            filesSet.add(path.resolve(arg, f));
+          }
+        });
+      }
+    } else {
+      // Handle simple wildcard pattern like *.md or docs/*.md
+      const dir = path.dirname(arg) || '.';
+      const pattern = path.basename(arg);
+
+      if (fs.existsSync(dir)) {
+        const regexPattern = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$', 'i');
+        const dirFiles = fs.readdirSync(dir);
+        dirFiles.forEach(f => {
+          if (regexPattern.test(f) && (f.endsWith('.md') || f.endsWith('.markdown'))) {
+            filesSet.add(path.resolve(dir, f));
+          }
+        });
+      }
+    }
+  });
+
+  return Array.from(filesSet);
+}
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "md-pdf-studio",
+  "version": "1.1.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.",
+  "main": "src/core/index.js",
+  "bin": {
+    "md-pdf-studio": "bin/cli.js",
+    "md2pdf": "bin/cli.js",
+    "convert-md-to-pdf": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "scripts": {
+    "start": "node bin/cli.js",
+    "build:extension": "node scripts/build-extension.js",
+    "fetch:libs": "node scripts/fetch-vendor-libs.js",
+    "pre-commit": "node scripts/pre-commit.js",
+    "check:commit": "node scripts/check-commit.js",
+    "release": "node scripts/release.js",
+    "test": "node tests/index.test.js",
+    "test:sample": "node bin/cli.js examples/sample.md --toc -c examples/custom.css -o output_test.pdf"
+  },
+  "keywords": [
+    "markdown",
+    "pdf",
+    "cli",
+    "converter",
+    "chrome-extension",
+    "mermaid",
+    "katex",
+    "md2pdf",
+    "marked",
+    "md-pdf-studio",
+    "markdown-to-pdf"
+  ],
+  "author": "vannt-dev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vannt-dev/convert-md-to-pdf.git"
+  },
+  "homepage": "https://github.com/vannt-dev/convert-md-to-pdf#readme",
+  "bugs": {
+    "url": "https://github.com/vannt-dev/convert-md-to-pdf/issues"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "marked": "^12.0.2"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "devDependencies": {
+    "adm-zip": "^0.6.0"
+  }
+}

package/src/browser/renderer.js

@@ -0,0 +1,142 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFile } = require('child_process');
+
+/**
+ * Finds available Chrome or Edge binary path on system
+ * @returns {string|null}
+ */
+function findBrowserExecutable() {
+  const platform = os.platform();
+  const candidates = [];
+
+  if (platform === 'win32') {
+    const programFiles = process.env['PROGRAMFILES'] || 'C:\\Program Files';
+    const programFilesX86 = process.env['PROGRAMFILES(X86)'] || 'C:\\Program Files (x86)';
+    const localAppData = process.env['LOCALAPPDATA'] || path.join(os.homedir(), 'AppData', 'Local');
+
+    candidates.push(
+      path.join(programFilesX86, 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
+      path.join(programFiles, 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
+      path.join(programFiles, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+      path.join(programFilesX86, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+      path.join(localAppData, 'Google', 'Chrome', 'Application', 'chrome.exe')
+    );
+  } else if (platform === 'darwin') {
+    candidates.push(
+      '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+      '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+      '/Applications/Chromium.app/Contents/MacOS/Chromium'
+    );
+  } else {
+    // Linux / Unix
+    candidates.push(
+      '/usr/bin/google-chrome',
+      '/usr/bin/microsoft-edge',
+      '/usr/bin/chromium-browser',
+      '/usr/bin/chromium'
+    );
+  }
+
+  for (const binPath of candidates) {
+    if (fs.existsSync(binPath)) {
+      return binPath;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Renders HTML file to PDF using headless browser
+ * @param {string} htmlPath 
+ * @param {string} outputPath 
+ * @param {Object} options 
+ * @returns {Promise<string>}
+ */
+function renderHtmlToPdf(htmlPath, outputPath, options = {}) {
+  return new Promise((resolve, reject) => {
+    const browserPath = options.executablePath || findBrowserExecutable();
+
+    if (!browserPath) {
+      return reject(new Error('No installed Chromium browser (Edge/Chrome) was found on your system. Please install Microsoft Edge or Google Chrome.'));
+    }
+
+    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
+    ];
+
+    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
+        ];
+
+        execFile(browserPath, fallbackArgs, { timeout: 30000 }, (err2) => {
+          if (err2) {
+            return reject(new Error(`Failed to render PDF using browser: ${err2.message}`));
+          }
+          if (fs.existsSync(outputPath)) {
+            resolve(outputPath);
+          } else {
+            reject(new Error('Browser finished but output PDF file was not created.'));
+          }
+        });
+        return;
+      }
+
+      if (fs.existsSync(outputPath)) {
+        resolve(outputPath);
+      } else {
+        reject(new Error('Browser finished but output PDF file was not created.'));
+      }
+    });
+  });
+}
+
+/**
+ * Renders multiple HTML files to PDF using concurrent browser execution pool
+ * @param {Array<{ htmlPath: string, outputPath: string }>} itemPairs 
+ * @param {Object} options 
+ * @returns {Promise<Array<string>>}
+ */
+async function renderBatchHtmlToPdf(itemPairs, options = {}) {
+  const concurrency = Math.min(options.concurrency || 4, itemPairs.length);
+  const results = [];
+  const queue = [...itemPairs];
+
+  async function worker() {
+    while (queue.length > 0) {
+      const item = queue.shift();
+      if (!item) break;
+      const pdfPath = await renderHtmlToPdf(item.htmlPath, item.outputPath, options);
+      results.push(pdfPath);
+    }
+  }
+
+  const workers = Array.from({ length: concurrency }, () => worker());
+  await Promise.all(workers);
+  return results;
+}
+
+module.exports = {
+  findBrowserExecutable,
+  renderHtmlToPdf,
+  renderBatchHtmlToPdf
+};
+

package/src/core/cover.js

@@ -0,0 +1,40 @@
+/**
+ * Cover Page Generator Utility
+ */
+const { escapeHtml } = require('./sanitizer');
+
+/**
+ * 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;
+  
+  if (!cover && !subtitle && !author && !date) {
+    return '';
+  }
+
+  const docTitle = title || 'Document Report';
+  const docSubtitle = subtitle || '';
+  const docAuthor = author || '';
+  const docDate = date || '';
+
+  return `<div class="cover-page">
+  <div class="cover-page-inner">
+    <div class="cover-badge">DOCUMENT REPORT</div>
+    <h1 class="cover-title">${escapeHtml(docTitle)}</h1>
+    ${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>` : ''}
+    </div>
+  </div>
+</div>
+<div class="page-break"></div>\n`;
+}
+
+module.exports = {
+  generateCoverPage
+};