md-pdf-studio 2.3.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`).
@@ -31,6 +37,7 @@
 - 📐 **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.
@@ -123,6 +130,9 @@ toc: true
 | `--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` |
@@ -132,6 +142,7 @@ toc: true
 | `--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` |
 
 ---
 
@@ -152,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
 ...
@@ -159,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:
@@ -219,18 +234,20 @@ convert-md-to-pdf/
 │   │   ├── 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,9 +1,11 @@
 #!/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'];
@@ -28,12 +30,16 @@ 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 {
@@ -60,6 +66,7 @@ program
         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;
@@ -97,12 +104,17 @@ 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
           });
 
@@ -206,4 +218,4 @@ function expandInputFiles(args) {
   return Array.from(filesSet);
 }
 
-program.parse(process.argv);
+program.parse(normalizePageNumbersArgs(process.argv));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "md-pdf-studio",
-  "version": "2.3.0",
+  "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": {
@@ -59,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,13 +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>\n`;
 }
 
 module.exports = {
+  coverLabels,
   generateCoverPage
 };

package/src/core/docmodel.js

@@ -1,3 +1,4 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 const { marked } = require('marked');
 const { parseFrontMatter } = require('./frontmatter');
 const { applyFootnotes } = require('./footnotes');

package/src/core/docx.js

@@ -1,3 +1,4 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 const { buildDocument, collectHeadings, isPortableLink, plainText } = require('./docmodel');
 const { readLocalImage } = require('./images');
 const { createZip } = require('./zip');

package/src/core/epub.js

@@ -1,3 +1,4 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 const crypto = require('crypto');
 const hljs = require('highlight.js/lib/common');
 const { buildDocument, collectHeadings, isPortableLink, plainText } = require('./docmodel');

package/src/core/footnotes.js

@@ -1,3 +1,4 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 /**
  * Markdown footnotes: `text[^id]` in the body, `[^id]: note` anywhere on a line of its own.
  *

package/src/core/frontmatter.js

@@ -1,3 +1,4 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 /**
  * Front Matter Parser Utility
  */

package/src/core/images.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');
 

package/src/core/include.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 { parseFrontMatter } = require('./frontmatter');

package/src/core/index.js

@@ -1,8 +1,9 @@
+/*! 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 { parseMarkdownToHtml } = require('./parser');
 const { renderHtmlToPdf } = require('../browser/renderer');
-const { resolvePath } = require('./utils');
+const { resolvePath, parseFrontMatter } = require('./utils');
 const { expandIncludes } = require('./include');
 const { markdownToDocx } = require('./docx');
 const { markdownToEpub } = require('./epub');
@@ -29,6 +30,18 @@ function temporaryHtmlPath(absInputPath, absOutputPath) {
   }
 }
 
+/**
+ * Whether the PDF gets bookmarks from its headings: on unless `outline: false` is passed
+ * or set in the front matter (an option wins over the front matter).
+ * @param {string} markdown
+ * @param {Object} options
+ * @returns {boolean}
+ */
+function pdfOutline(markdown, options = {}) {
+  if (options.outline !== undefined) return options.outline !== false;
+  return parseFrontMatter(markdown).data.outline !== false;
+}
+
 /**
  * Main function to convert a Markdown file: to PDF by default, or to the
  * format named in `options.format` (`html`, `docx`, `epub`)
@@ -98,8 +111,8 @@ async function convertMarkdownToPdf(inputPath, outputPath, options = {}) {
     // Save temporary HTML file
     fs.writeFileSync(tempHtmlPath, htmlContent, 'utf8');
 
-    // Render HTML to PDF via headless browser
-    await renderHtmlToPdf(tempHtmlPath, absOutputPath, options);
+    // Render HTML to PDF via headless browser, with bookmarks unless turned off
+    await renderHtmlToPdf(tempHtmlPath, absOutputPath, { ...options, outline: pdfOutline(markdownContent, options) });
 
     // Clean up temporary HTML file unless explicitly requested to keep
     if (!options.keepHtml) {
@@ -129,6 +142,7 @@ module.exports = {
   markdownToDocx,
   markdownToEpub,
   parseMarkdownToHtml,
+  pdfOutline,
   renderHtmlToPdf,
   temporaryHtmlPath
 };

package/src/core/pagemarks.js

@@ -0,0 +1,142 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
+/**
+ * Page numbers and a running header/footer, printed in the page margins with CSS `@page`
+ * margin boxes. Chrome and Edge draw these both for `--print-to-pdf` and in their print
+ * dialog, so the CLI and the extension share this file: it needs nothing from Node and is
+ * shipped in the extension as extension/lib/pagemarks.js (a test keeps the two identical).
+ *
+ * Header and footer are text with placeholders: {page}, {pages}, {title}, {author}, {date}.
+ */
+(function (scope) {
+  const NUMBER_STYLES = {
+    full: 'Page {page} of {pages}',
+    simple: '{page}'
+  };
+  const DEFAULT_HEADER = '{title}';
+  const PLACEHOLDER = /\{(page|pages|title|author|date)\}/g;
+
+  /**
+   * The text for a header or footer option: a string as it is, `true` for the default.
+   * @param {*} value
+   * @param {string} fallback Text used for `true`
+   * @returns {string} '' when off
+   */
+  function textOf(value, fallback) {
+    if (value === true) return fallback;
+    if (typeof value === 'number') return String(value);
+    return typeof value === 'string' ? value.trim() : '';
+  }
+
+  /**
+   * The page number text for the `pageNumbers` option.
+   * @param {*} value true, 'full', 'simple', or false/empty for none
+   * @returns {string} '' when off
+   */
+  function numbersOf(value) {
+    if (value === undefined || value === null || value === false || value === '') return '';
+    if (value === true) return NUMBER_STYLES.full;
+    const style = String(value).trim().toLowerCase();
+    if (style === 'true') return NUMBER_STYLES.full;
+    if (style === 'false' || style === 'none' || style === 'off') return '';
+    if (!NUMBER_STYLES[style]) {
+      throw new Error(`Unknown page number style "${value}". Use one of: ${Object.keys(NUMBER_STYLES).join(', ')}`);
+    }
+    return NUMBER_STYLES[style];
+  }
+
+  /**
+   * A CSS string literal that cannot end early or close the <style> element.
+   * @param {string} text
+   * @returns {string}
+   */
+  function cssString(text) {
+    const safe = text
+      .replace(/\\/g, '\\\\')
+      .replace(/"/g, '\\"')
+      .replace(/[\r\n]+/g, ' ')
+      .replace(/</g, '\\3C ');
+    return `"${safe}"`;
+  }
+
+  /**
+   * Turns header/footer text into the value of a CSS `content` property.
+   * @param {string} text
+   * @param {{ title?: string, author?: string, date?: string }} meta
+   * @returns {string}
+   */
+  function contentValue(text, meta = {}) {
+    const parts = [];
+    let literal = '';
+    let last = 0;
+    for (const match of text.matchAll(PLACEHOLDER)) {
+      literal += text.slice(last, match.index);
+      last = match.index + match[0].length;
+      const name = match[1];
+      if (name === 'page' || name === 'pages') {
+        if (literal) parts.push(cssString(literal));
+        literal = '';
+        parts.push(`counter(${name})`);
+      } else {
+        literal += meta[name] ? String(meta[name]) : '';
+      }
+    }
+    literal += text.slice(last);
+    if (literal) parts.push(cssString(literal));
+    return parts.length ? parts.join(' ') : '""';
+  }
+
+  /**
+   * Where each text goes. The header sits top centre. The footer sits bottom centre, unless
+   * page numbers are also on: then the footer text goes left and the numbers right.
+   * @param {{ header?: *, footer?: *, pageNumbers?: * }} options
+   * @returns {Object<string, string>} margin box name -> text
+   */
+  function pageMarkBoxes(options = {}) {
+    const header = textOf(options.header, DEFAULT_HEADER);
+    const numbers = numbersOf(options.pageNumbers);
+    const footer = textOf(options.footer, NUMBER_STYLES.full);
+    const boxes = {};
+    if (header) boxes['top-center'] = header;
+    if (footer && numbers && footer !== numbers) {
+      boxes['bottom-left'] = footer;
+      boxes['bottom-right'] = numbers;
+    } else if (footer || numbers) {
+      boxes['bottom-center'] = footer || numbers;
+    }
+    return boxes;
+  }
+
+  /**
+   * CSS for the page numbers and running header/footer, or '' when none is on.
+   * A cover page (.cover-page) is printed without them.
+   * @param {{ header?: *, footer?: *, pageNumbers?: *, font?: string }} options
+   * @param {{ title?: string, author?: string, date?: string }} [meta]
+   * @returns {string}
+   */
+  function pageMarksCss(options = {}, meta = {}) {
+    const boxes = pageMarkBoxes(options);
+    const names = Object.keys(boxes);
+    if (!names.length) return '';
+
+    const font = options.font ? `${cssString(String(options.font))}, sans-serif` : 'sans-serif';
+    const style = `font-family: ${font}; font-size: 9px; color: #64748b;`;
+    const rules = names.map(
+      (name) => `  @${name} { content: ${contentValue(boxes[name], meta)}; ${style} }`
+    );
+    const blank = names.map((name) => `  @${name} { content: none; }`);
+    return [
+      '/* Page numbers and running header/footer */',
+      '@page {',
+      ...rules,
+      '}',
+      '.cover-page { page: cover; }',
+      '@page cover {',
+      ...blank,
+      '}'
+    ].join('\n');
+  }
+
+  const api = { pageMarksCss, pageMarkBoxes, contentValue };
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else scope.MdPdfPageMarks = api;
+})(typeof globalThis !== 'undefined' ? globalThis : this);

package/src/core/parser.js

@@ -1,3 +1,4 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 const { marked } = require('marked');
 const hljs = require('highlight.js/lib/common');
 const { 
@@ -11,6 +12,7 @@ const {
 } = require('./utils');
 const { getHtmlTemplate } = require('./templates');
 const { applyFootnotes } = require('./footnotes');
+const { pageMarksCss } = require('./pagemarks');
 
 /**
  * Builds marked custom renderer for diagrams, UI mockups, and headings
@@ -82,6 +84,8 @@ function parseMarkdownToHtml(rawMarkdownContent, options = {}) {
   const subtitle = frontMatter.subtitle || options.subtitle || '';
   const author = frontMatter.author || options.author || '';
   const date = frontMatter.date || options.date || '';
+  // Document language, as for EPUB: sets the cover labels and the page's lang attribute
+  const language = String(frontMatter.lang || frontMatter.language || options.language || 'en');
 
   // 2. Merge options
   const mergedOptions = {
@@ -92,8 +96,10 @@ function parseMarkdownToHtml(rawMarkdownContent, options = {}) {
     margin: options.margin || frontMatter.margin || '14mm 12mm 16mm 12mm',
     toc: options.toc !== undefined ? options.toc : (frontMatter.toc || false),
     cover: options.cover !== undefined ? options.cover : (frontMatter.cover || false),
-    header: options.header !== undefined ? options.header : (frontMatter.header || true),
-    footer: options.footer !== undefined ? options.footer : (frontMatter.footer || true),
+    // Running header/footer and page numbers: off unless asked for (see pagemarks.js)
+    header: options.header !== undefined ? options.header : frontMatter.header,
+    footer: options.footer !== undefined ? options.footer : frontMatter.footer,
+    pageNumbers: options.pageNumbers !== undefined ? options.pageNumbers : frontMatter.pageNumbers,
     mermaid: options.mermaid !== undefined ? options.mermaid : (frontMatter.mermaid !== false),
     katex: options.katex !== undefined ? options.katex : (frontMatter.katex !== false),
     highlight: options.highlight !== undefined ? options.highlight : (frontMatter.highlight !== false),
@@ -118,7 +124,8 @@ function parseMarkdownToHtml(rawMarkdownContent, options = {}) {
     subtitle,
     author,
     date,
-    cover: mergedOptions.cover
+    cover: mergedOptions.cover,
+    language
   });
 
   // 5. Read custom CSS file if specified
@@ -127,6 +134,15 @@ function parseMarkdownToHtml(rawMarkdownContent, options = {}) {
     customCss += '\n' + readCustomCss(mergedOptions.cssFile);
   }
 
+  // Page numbers and running header/footer, printed in the page margins
+  const pageCss = pageMarksCss(
+    { header: mergedOptions.header, footer: mergedOptions.footer, pageNumbers: mergedOptions.pageNumbers, font: mergedOptions.font },
+    { title, author, date }
+  );
+  if (pageCss) {
+    customCss = pageCss + '\n' + customCss;
+  }
+
   // 6. Parse Markdown using custom renderer
   marked.setOptions({ gfm: true, breaks: true });
   const renderer = buildMarkedRenderer(headingsMap, mergedOptions.highlight);
@@ -152,6 +168,7 @@ function parseMarkdownToHtml(rawMarkdownContent, options = {}) {
   return getHtmlTemplate({
     title,
     author,
+    language,
     bodyHtml,
     options: {
       ...mergedOptions,

package/src/core/sanitizer.js

@@ -1,3 +1,4 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 /**
  * HTML Sanitizer & Escaping Utilities
  */

package/src/core/templates.js

@@ -1,3 +1,4 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 const { getThemeStyles } = require('./themes');
 
 /**
@@ -15,11 +16,12 @@ function escapeXml(str) {
  * @param {Object} params
  * @param {string} params.title Document title
  * @param {string} [params.author] Document author
+ * @param {string} [params.language] Document language tag (default en)
  * @param {string} params.bodyHtml Document body HTML
  * @param {Object} [params.options] Template options
  * @returns {string} Full HTML string
  */
-function getHtmlTemplate({ title, author = '', bodyHtml, options = {} }) {
+function getHtmlTemplate({ title, author = '', language = 'en', bodyHtml, options = {} }) {
   const theme = options.theme || 'modern';
   const enableMermaid = options.mermaid !== false;
   const enableKatex = options.katex !== false;
@@ -31,7 +33,7 @@ function getHtmlTemplate({ title, author = '', bodyHtml, options = {} }) {
   const themeStyles = getThemeStyles(theme, options.font);
 
   return `<!DOCTYPE html>
-<html lang="vi">
+<html lang="${escapeXml(language)}">
 <head>
   <meta charset="UTF-8">
   <title>${escapeXml(title)}</title>

package/src/core/themes/academic.js

@@ -1,3 +1,4 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 /**
  * Academic Theme Styles
  */

package/src/core/themes/cover.js

@@ -1,3 +1,4 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 /**
  * Cover Page CSS Styles
  */

package/src/core/themes/cyberpunk.js

@@ -1,3 +1,4 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 /**
  * Cyberpunk Theme Styles
  */

package/src/core/themes/dark.js

@@ -1,3 +1,4 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 /**
  * Dark Theme Styles
  */

package/src/core/themes/ebook.js

@@ -1,3 +1,4 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 /**
  * E-Book Theme Styles
  */

package/src/core/themes/github.js

@@ -1,3 +1,4 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 /**
  * GitHub Theme Styles
  */

package/src/core/themes/highlight.js

@@ -1,3 +1,4 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 /**
  * Syntax Highlighting Token Colors
  * Two palettes, picked by the background each theme gives its code blocks.

package/src/core/themes/index.js

@@ -1,3 +1,4 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 const coverCss = require('./cover');
 const modernTheme = require('./modern');
 const darkTheme = require('./dark');

package/src/core/themes/minimal.js

@@ -1,3 +1,4 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 /**
  * Minimal Theme Styles
  */

package/src/core/themes/modern.js

@@ -1,3 +1,4 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 /**
  * Modern Theme Styles
  */

package/src/core/toc.js

@@ -1,3 +1,4 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 /**
  * Table of Contents (TOC) Generator Utility
  */

package/src/core/utils.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 { parseFrontMatter } = require('./frontmatter');

package/src/core/zip.js

@@ -1,3 +1,4 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 const zlib = require('zlib');
 
 /**

package/src/index.js

@@ -1,2 +1,3 @@
+/*! SPDX-License-Identifier: MIT | Copyright (c) 2026 Van Nguyen | github.com/vannt-dev/convert-md-to-pdf */
 // Re-export core API module
 module.exports = require('./core/index');