@brahim.ariani/md2pdf-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brahim Ariani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# md2pdf-cli
+
+Convert Markdown files into beautifully styled PDFs using [marked](https://github.com/markedjs/marked), [KaTeX](https://katex.org/) and [puppeteer](https://github.com/puppeteer/puppeteer).
+
+GitHub-flavored Markdown, tables, code blocks, blockquotes, images **and LaTeX math equations** (`$inline$` and `$$display$$`) are all rendered with sane, print-friendly defaults — page numbers in the footer, A4 by default, justified body text, and zebra-striped tables.
+
+## Install
+
+```bash
+npm install -g md2pdf-cli
+```
+
+Or use it directly in a project:
+
+```bash
+npm install md2pdf-cli
+```
+
+## CLI
+
+```bash
+md2pdf <input.md> [output.pdf] [options]
+```
+
+If `output.pdf` is omitted, the output filename is derived from the input (e.g. `research.md` → `research.pdf`).
+
+### Options
+
+| Flag                   | Description                                                |
+|------------------------|------------------------------------------------------------|
+| `--title <text>`       | Document title (defaults to the input filename)            |
+| `--css <file>`         | Path to a custom CSS file (replaces the default styles)    |
+| `--format <size>`      | Page format: `A4`, `Letter`, `Legal`, ... Default: `A4`    |
+| `--no-page-numbers`    | Disable the page-number footer                             |
+| `--no-math`            | Disable KaTeX equation rendering                           |
+| `--keep-html`          | Keep the intermediate `.tmp.html` file for debugging       |
+| `-h`, `--help`         | Show usage                                                 |
+
+### Examples
+
+```bash
+md2pdf research.md
+md2pdf research.md out/research.pdf
+md2pdf report.md report.pdf --title "Quarterly Report" --css theme.css
+md2pdf notes.md notes.pdf --format Letter --no-page-numbers
+md2pdf paper.md paper.pdf            # equations rendered by default
+md2pdf draft.md draft.pdf --no-math  # treat $...$ as literal text
+```
+
+### Math / LaTeX equations
+
+Inline math uses single dollars, display math uses double dollars:
+
+```markdown
+The famous identity is $e^{i\pi} + 1 = 0$.
+
+$$
+\int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}
+$$
+```
+
+Equations are rendered server-side with KaTeX, so the PDF is self-contained and prints identically on any machine.
+
+## Programmatic API
+
+```js
+const { convert } = require('md2pdf-cli');
+
+await convert({
+  input: 'research.md',
+  output: 'research.pdf',
+  title: 'My Research Report',
+  // cssFile: 'theme.css',
+  // css: '/* inline CSS string */',
+  format: 'A4',
+  pageNumbers: true,
+});
+```
+
+### `convert(options)`
+
+| Option              | Type                          | Default                | Description                                            |
+|---------------------|-------------------------------|------------------------|--------------------------------------------------------|
+| `input`             | `string`                      | —                      | Path to a Markdown file (required)                     |
+| `output`            | `string`                      | —                      | Path to the output PDF (required)                      |
+| `title`             | `string`                      | input basename         | `<title>` of the generated HTML                        |
+| `css`               | `string`                      | bundled default        | Inline CSS string                                      |
+| `cssFile`           | `string`                      | —                      | Path to a CSS file (overrides `css`)                   |
+| `format`            | `string`                      | `'A4'`                 | Puppeteer page format                                  |
+| `margin`            | `object`                      | 22mm / 18mm            | `{ top, bottom, left, right }`                         |
+| `pageNumbers`       | `boolean`                     | `true`                 | Render `n / total` in the footer                       |
+| `math`              | `boolean`                     | `true`                 | Render `$...$` and `$$...$$` as KaTeX                  |
+| `headerTemplate`    | `string`                      | empty                  | Puppeteer header HTML                                  |
+| `footerTemplate`    | `string`                      | page numbers           | Puppeteer footer HTML                                  |
+| `puppeteerOptions`  | `object`                      | `{}`                   | Extra options passed to `puppeteer.launch`             |
+| `keepHtml`          | `boolean`                     | `false`                | Keep the intermediate `.tmp.html` file                 |
+
+Returns `{ output, brokenImages }` where `brokenImages` lists any `<img>` URLs that failed to load.
+
+## Requirements
+
+- Node.js >= 18
+- Puppeteer will download a compatible Chromium on install (≈ 170 MB). To skip this and reuse an existing Chrome, set `PUPPETEER_SKIP_DOWNLOAD=true` before installing and pass `puppeteerOptions: { executablePath: '...' }` to `convert()`.
+
+## License
+
+MIT

package/bin/md2pdf.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const { convert } = require('../lib/index');
+
+function printUsage() {
+  console.log(`Usage:
+  md2pdf <input.md> [output.pdf] [options]
+
+Options:
+  --title <text>        Document title (defaults to input filename)
+  --css <file>          Path to a custom CSS file (replaces the default styles)
+  --format <size>       Page format (A4, Letter, ...). Default: A4
+  --no-page-numbers     Disable footer page numbers
+  --no-math             Disable KaTeX equation rendering ($...$ / $$...$$)
+  --keep-html           Keep the intermediate .tmp.html file
+  -h, --help            Show this help
+
+Examples:
+  md2pdf research.md
+  md2pdf research.md out/research.pdf
+  md2pdf report.md report.pdf --title "Quarterly Report" --css theme.css
+`);
+}
+
+function parseArgs(argv) {
+  const args = { positional: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') { args.flags.help = true; continue; }
+    if (a === '--no-page-numbers') { args.flags.pageNumbers = false; continue; }
+    if (a === '--no-math') { args.flags.math = false; continue; }
+    if (a === '--keep-html') { args.flags.keepHtml = true; continue; }
+    if (a === '--title') { args.flags.title = argv[++i]; continue; }
+    if (a === '--css') { args.flags.cssFile = argv[++i]; continue; }
+    if (a === '--format') { args.flags.format = argv[++i]; continue; }
+    if (a.startsWith('--')) {
+      console.error(`Unknown option: ${a}`);
+      process.exit(2);
+    }
+    args.positional.push(a);
+  }
+  return args;
+}
+
+(async () => {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.flags.help || args.positional.length === 0) {
+    printUsage();
+    process.exit(args.flags.help ? 0 : 1);
+  }
+
+  const input = args.positional[0];
+  const output =
+    args.positional[1] ||
+    input.replace(/\.md$/i, '') + '.pdf';
+
+  try {
+    const result = await convert({
+      input,
+      output,
+      title: args.flags.title,
+      cssFile: args.flags.cssFile,
+      format: args.flags.format || 'A4',
+      pageNumbers: args.flags.pageNumbers !== false,
+      math: args.flags.math !== false,
+      keepHtml: !!args.flags.keepHtml,
+    });
+    if (result.brokenImages && result.brokenImages.length) {
+      console.warn('WARNING: broken images:');
+      for (const src of result.brokenImages) console.warn('  -', src);
+    }
+    console.log('PDF generated:', result.output);
+  } catch (err) {
+    console.error('Error:', err.message);
+    process.exit(1);
+  }
+})();

package/lib/index.js

@@ -0,0 +1,184 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { marked } = require('marked');
+const markedKatex = require('marked-katex-extension');
+const puppeteer = require('puppeteer');
+const { defaultCss, katexCssLink } = require('./styles');
+
+let katexExtensionRegistered = false;
+function ensureKatexExtension() {
+  if (katexExtensionRegistered) return;
+  marked.use(markedKatex({ throwOnError: false, output: 'html', nonStandard: true }));
+  katexExtensionRegistered = true;
+}
+
+function buildHtml({ body, title, css, math }) {
+  const katexTag = math ? katexCssLink() : '';
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>${escapeHtml(title)}</title>
+${katexTag}
+<style>${css}</style>
+</head>
+<body>
+${body}
+</body>
+</html>`;
+}
+
+function escapeHtml(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+// marked-katex-extension only treats `$$...$$` as a display-math block when
+// surrounded by blank lines. Normalize the source so users don't trip on it.
+function normalizeBlockMath(src) {
+  const lines = src.split(/\r?\n/);
+  const out = [];
+  let inFence = false;
+  let inMath = false;
+  const pushBlankIfNeeded = () => {
+    if (out.length > 0 && out[out.length - 1].trim() !== '') out.push('');
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (!inMath && /^(```|~~~)/.test(trimmed)) {
+      inFence = !inFence;
+      out.push(line);
+      continue;
+    }
+    if (inFence) { out.push(line); continue; }
+    const singleBlock = /^\$\$[^$]+\$\$$/.test(trimmed);
+    const opensBlock  = !inMath && !singleBlock && /^\$\$/.test(trimmed) && !/\$\$.+\$\$$/.test(trimmed);
+    const closesBlock = inMath && /\$\$\s*$/.test(trimmed);
+    if (singleBlock) {
+      pushBlankIfNeeded();
+      out.push(line);
+      if (i + 1 < lines.length && lines[i + 1].trim() !== '') out.push('');
+      continue;
+    }
+    if (opensBlock) {
+      pushBlankIfNeeded();
+      inMath = true;
+      out.push(line);
+      continue;
+    }
+    if (closesBlock) {
+      inMath = false;
+      out.push(line);
+      if (i + 1 < lines.length && lines[i + 1].trim() !== '') out.push('');
+      continue;
+    }
+    out.push(line);
+  }
+  return out.join('\n');
+}
+
+async function convert(options) {
+  const {
+    input,
+    output,
+    title,
+    css,
+    cssFile,
+    format = 'A4',
+    margin = { top: '22mm', bottom: '22mm', left: '18mm', right: '18mm' },
+    pageNumbers = true,
+    headerTemplate,
+    footerTemplate,
+    puppeteerOptions = {},
+    keepHtml = false,
+    math = true,
+  } = options;
+
+  if (!input) throw new Error('`input` is required');
+  if (!output) throw new Error('`output` is required');
+
+  const inputAbs = path.resolve(input);
+  const outputAbs = path.resolve(output);
+
+  if (!fs.existsSync(inputAbs)) {
+    throw new Error(`Input markdown file not found: ${inputAbs}`);
+  }
+
+  const rawMd = fs.readFileSync(inputAbs, 'utf8');
+  marked.setOptions({ gfm: true, breaks: false });
+  if (math) ensureKatexExtension();
+  const md = math ? normalizeBlockMath(rawMd) : rawMd;
+  const body = marked.parse(md);
+
+  let resolvedCss = css || defaultCss;
+  if (cssFile) {
+    resolvedCss = fs.readFileSync(path.resolve(cssFile), 'utf8');
+  }
+
+  const docTitle = title || path.basename(inputAbs, path.extname(inputAbs));
+  const html = buildHtml({ body, title: docTitle, css: resolvedCss, math });
+
+  const tmpHtmlPath = outputAbs.replace(/\.pdf$/i, '') + '.tmp.html';
+  fs.writeFileSync(tmpHtmlPath, html, 'utf8');
+  const fileUrl = 'file:///' + tmpHtmlPath.replace(/\\/g, '/');
+
+  const launchOptions = Object.assign(
+    { headless: true, args: ['--no-sandbox', '--disable-setuid-sandbox'] },
+    puppeteerOptions
+  );
+
+  const browser = await puppeteer.launch(launchOptions);
+  try {
+    const page = await browser.newPage();
+    await page.goto(fileUrl, { waitUntil: ['load', 'networkidle0'] });
+
+    await page.evaluate(async () => {
+      const imgs = Array.from(document.images);
+      await Promise.all(imgs.map((img) => {
+        if (img.complete && img.naturalWidth > 0) return;
+        return new Promise((res) => {
+          img.addEventListener('load', res);
+          img.addEventListener('error', res);
+        });
+      }));
+    });
+
+    const broken = await page.evaluate(() =>
+      Array.from(document.images)
+        .filter((img) => !img.complete || img.naturalWidth === 0)
+        .map((img) => img.src)
+    );
+
+    const pdfOptions = {
+      path: outputAbs,
+      format,
+      printBackground: true,
+      margin,
+    };
+
+    if (pageNumbers || headerTemplate || footerTemplate) {
+      pdfOptions.displayHeaderFooter = true;
+      pdfOptions.headerTemplate = headerTemplate || '<div></div>';
+      pdfOptions.footerTemplate =
+        footerTemplate ||
+        '<div style="font-size:8pt; color:#64748b; width:100%; text-align:center;">' +
+        '<span class="pageNumber"></span> / <span class="totalPages"></span>' +
+        '</div>';
+    }
+
+    await page.pdf(pdfOptions);
+    return { output: outputAbs, brokenImages: broken };
+  } finally {
+    await browser.close();
+    if (!keepHtml) {
+      try { fs.unlinkSync(tmpHtmlPath); } catch (_) { /* ignore */ }
+    }
+  }
+}
+
+module.exports = { convert, defaultCss };

package/lib/styles.js

@@ -0,0 +1,103 @@
+'use strict';
+
+const path = require('path');
+
+function katexCssLink() {
+  let katexCssPath;
+  try {
+    katexCssPath = require.resolve('katex/dist/katex.min.css');
+  } catch (_) {
+    return '<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css">';
+  }
+  const fileUrl = 'file:///' + katexCssPath.replace(/\\/g, '/');
+  return `<link rel="stylesheet" href="${fileUrl}">`;
+}
+
+const defaultCss = `
+@page { size: A4; margin: 22mm 18mm 22mm 18mm; }
+* { box-sizing: border-box; }
+body {
+  font-family: "Segoe UI", "Helvetica Neue", Arial, sans-serif;
+  font-size: 11pt;
+  line-height: 1.55;
+  color: #1a1a1a;
+  max-width: 100%;
+  margin: 0;
+}
+h1, h2, h3, h4 {
+  color: #102a43;
+  page-break-after: avoid;
+  break-after: avoid;
+}
+h1 { font-size: 22pt; border-bottom: 2px solid #102a43; padding-bottom: 6px; margin-top: 0; }
+h2 { font-size: 16pt; border-bottom: 1px solid #bcccdc; padding-bottom: 4px; margin-top: 28px; }
+h3 { font-size: 13pt; margin-top: 22px; }
+h4 { font-size: 11.5pt; margin-top: 18px; }
+p { text-align: justify; margin: 0 0 10px 0; }
+ul, ol { margin: 6px 0 12px 0; padding-left: 24px; }
+li { margin-bottom: 4px; }
+strong { color: #0b2447; }
+code {
+  background: #f1f5f9;
+  padding: 1px 5px;
+  border-radius: 3px;
+  font-family: "Consolas", "Courier New", monospace;
+  font-size: 9.5pt;
+  color: #b91c1c;
+}
+pre {
+  background: #0f172a;
+  color: #f1f5f9;
+  padding: 12px;
+  border-radius: 5px;
+  overflow-x: auto;
+  font-size: 9pt;
+}
+pre code { background: transparent; color: inherit; padding: 0; }
+table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 12px 0 18px 0;
+  page-break-inside: avoid;
+  font-size: 9.5pt;
+}
+th, td {
+  border: 1px solid #cbd5e1;
+  padding: 6px 9px;
+  text-align: left;
+  vertical-align: top;
+}
+th { background: #e2e8f0; color: #0b2447; font-weight: 600; }
+tr:nth-child(even) td { background: #f8fafc; }
+hr { border: none; border-top: 1px solid #cbd5e1; margin: 24px 0; }
+blockquote {
+  border-left: 4px solid #64748b;
+  padding: 4px 12px;
+  color: #475569;
+  background: #f8fafc;
+  margin: 10px 0;
+}
+img {
+  max-width: 100%;
+  height: auto;
+  display: block;
+  margin: 12px auto;
+  border: 1px solid #e2e8f0;
+  border-radius: 4px;
+  page-break-inside: avoid;
+  break-inside: avoid;
+}
+img + em, p > em {
+  display: block;
+  text-align: center;
+  color: #475569;
+  font-size: 9.5pt;
+  margin-bottom: 14px;
+}
+a { color: #1d4ed8; text-decoration: none; }
+.katex { font-size: 1.05em; }
+.katex-display { margin: 14px 0; overflow-x: auto; overflow-y: hidden; page-break-inside: avoid; }
+.katex-display > .katex { display: inline-block; text-align: center; max-width: 100%; }
+`;
+
+module.exports = { defaultCss, katexCssLink };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@brahim.ariani/md2pdf-cli",
+  "version": "1.0.0",
+  "description": "Convert Markdown files to beautifully styled PDFs using marked and puppeteer.",
+  "keywords": [
+    "markdown",
+    "pdf",
+    "md-to-pdf",
+    "puppeteer",
+    "marked",
+    "katex",
+    "math",
+    "latex",
+    "equations",
+    "cli",
+    "converter"
+  ],
+  "license": "MIT",
+  "author": "Brahim Ariani <brahim.ariani.inc@gmail.com>",
+  "main": "lib/index.js",
+  "bin": {
+    "md2pdf": "bin/md2pdf.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test/smoke.js"
+  },
+  "dependencies": {
+    "katex": "^0.16.9",
+    "marked": "^12.0.0",
+    "marked-katex-extension": "^5.0.0",
+    "puppeteer": "^24.15.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/brahimariani/md2pdf-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/brahimariani/md2pdf-cli/issues"
+  },
+  "homepage": "https://github.com/brahimariani/md2pdf-cli#readme"
+}