@brahim.ariani/md2pdf-cli 1.0.0 → 1.2.0

package/README.md

@@ -7,13 +7,13 @@ GitHub-flavored Markdown, tables, code blocks, blockquotes, images **and LaTeX m
 ## Install
 
 ```bash
-npm install -g md2pdf-cli
+npm install -g @brahim.ariani/md2pdf-cli
 ```
 
 Or use it directly in a project:
 
 ```bash
-npm install md2pdf-cli
+npm install brahim.ariani/md2pdf-cli
 ```
 
 ## CLI
@@ -30,9 +30,20 @@ If `output.pdf` is omitted, the output filename is derived from the input (e.g.
 |------------------------|------------------------------------------------------------|
 | `--title <text>`       | Document title (defaults to the input filename)            |
 | `--css <file>`         | Path to a custom CSS file (replaces the default styles)    |
+| `--theme <name>`       | Built-in theme: `default`, `academic`, `latex`             |
 | `--format <size>`      | Page format: `A4`, `Letter`, `Legal`, ... Default: `A4`    |
+| `--toc`                | Prepend an auto-generated table of contents                |
+| `--toc-depth <n>`      | Deepest heading level included in the TOC. Default: `3`    |
+| `--toc-title <text>`   | TOC heading text. Default: `Contents`                      |
+| `--highlight`          | Syntax-highlight fenced code blocks with Shiki             |
+| `--code-theme <name>`  | Shiki theme for code blocks. Default: `github-light`       |
+| `--mermaid`            | Render ` ```mermaid ` code blocks as diagrams              |
+| `--mermaid-theme <t>`  | Mermaid theme: `base`, `default`, `neutral`, `dark`, `forest`. Default: `base` |
+| `--cover`              | Render a title page from YAML front matter                 |
+| `--no-cover`           | Never render a title page (overrides front matter)         |
 | `--no-page-numbers`    | Disable the page-number footer                             |
 | `--no-math`            | Disable KaTeX equation rendering                           |
+| `--no-sanitize`        | Disable HTML sanitization (**unsafe**, see below)          |
 | `--keep-html`          | Keep the intermediate `.tmp.html` file for debugging       |
 | `-h`, `--help`         | Show usage                                                 |
 
@@ -43,6 +54,10 @@ 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 book.md book.pdf --toc --toc-depth 2 --toc-title "Table of Contents"
+md2pdf code.md code.pdf --highlight --code-theme github-dark
+md2pdf paper.md paper.pdf --cover --toc
+md2pdf thesis.md thesis.pdf --theme academic --toc
 md2pdf paper.md paper.pdf            # equations rendered by default
 md2pdf draft.md draft.pdf --no-math  # treat $...$ as literal text
 ```
@@ -61,6 +76,146 @@ $$
 
 Equations are rendered server-side with KaTeX, so the PDF is self-contained and prints identically on any machine.
 
+## Table of contents
+
+Pass `--toc` to prepend an auto-generated, clickable table of contents built
+from the document headings. Each heading also receives a stable `id` slug, so
+the TOC links resolve as in-document bookmarks.
+
+```bash
+md2pdf report.md report.pdf --toc                       # depth 3 (default)
+md2pdf report.md report.pdf --toc --toc-depth 2         # only h1 + h2
+md2pdf report.md report.pdf --toc --toc-title "Sommaire"
+```
+
+The TOC is placed on its own page (it ends with a page break). You can fully
+restyle it via `--css` by targeting `nav.toc`, `nav.toc .toc-title`, etc.
+
+## Themes
+
+Pick a built-in look with `--theme`:
+
+| Theme      | Description                                                          |
+|------------|----------------------------------------------------------------------|
+| `default`  | Clean sans-serif, navy headings, zebra tables (the original look)    |
+| `academic` | Georgia serif, justified & indented paragraphs, centered title       |
+| `latex`    | Classic LaTeX `article` look: Computer Modern serif, booktabs tables |
+
+```bash
+md2pdf report.md report.pdf --theme academic
+md2pdf thesis.md thesis.pdf --theme latex --toc
+md2pdf design.md design.pdf --mermaid --highlight --cover
+```
+
+Every theme keeps the same structural rules (math, TOC, cover page, tables,
+page-break safety) and only swaps typography and colors. An unknown theme name
+falls back to `default` with a warning. For full control, `--css` still
+replaces all styles entirely.
+
+## Front matter & cover page
+
+Markdown files may start with a YAML front-matter block. It is parsed, stripped
+from the body, and used to enrich the document:
+
+```markdown
+---
+title: Quarterly Report
+subtitle: Q2 2026 Financial Overview
+author:
+  - Brahim Ariani
+  - Finance Team
+date: 2026-05-31
+cover: true
+---
+
+# Introduction
+...
+```
+
+- `title` becomes the HTML document title (a `--title` flag still wins).
+- With `--cover` (or `cover: true` in the front matter), a dedicated **title
+  page** is rendered from `title`, `subtitle`, `author`/`authors` and `date`,
+  followed by a page break. `--no-cover` disables it even if the front matter
+  requests one.
+
+```bash
+md2pdf paper.md paper.pdf --cover
+md2pdf paper.md paper.pdf --cover --toc   # title page, then a TOC page
+```
+
+Restyle the cover via `--css` by targeting `section.cover`, `.cover-title`,
+`.cover-subtitle`, `.cover-author`, `.cover-date`.
+
+## Syntax highlighting
+
+Pass `--highlight` to colorize fenced code blocks with
+[Shiki](https://shiki.style/) (the same engine that powers VS Code). Colors are
+inlined into the HTML, so the PDF stays self-contained and prints identically
+everywhere — no client-side JavaScript or web fonts required.
+
+```bash
+md2pdf code.md code.pdf --highlight
+md2pdf code.md code.pdf --highlight --code-theme github-dark
+```
+
+Only the languages actually used in the document are loaded, keeping conversion
+fast. Use any Shiki theme name (e.g. `github-light`, `github-dark`, `nord`,
+`dracula`, `min-light`). Unknown languages fall back to a plain, escaped code
+block, and an unknown theme falls back to `github-light`.
+
+## Mermaid diagrams
+
+With `--mermaid`, fenced code blocks tagged `mermaid` are rendered into vector
+diagrams with [Mermaid](https://mermaid.js.org/) (flowcharts, sequence diagrams,
+Gantt charts, etc.):
+
+````markdown
+```mermaid
+flowchart LR
+  A[Start] --> B{OK?}
+  B -- Yes --> C[Ship]
+  B -- No  --> A
+```
+````
+
+```bash
+md2pdf design.md design.pdf --mermaid
+md2pdf design.md design.pdf --mermaid --mermaid-theme neutral
+```
+
+Diagrams are rendered inside the same headless Chromium used for printing, so
+the resulting SVG is embedded directly in the PDF — no network access or extra
+tooling required. Mermaid runs with `securityLevel: 'strict'`, and a diagram
+with invalid syntax is skipped rather than aborting the whole conversion.
+Without `--mermaid`, ` ```mermaid ` blocks are left as plain code.
+
+## Security / HTML sanitization
+
+Markdown allows raw HTML, which means an untrusted `.md` file can embed
+`<script>`, `<iframe>`, or event-handler attributes (`onerror`, `onclick`, ...).
+Because the document is rendered through a real browser (Chromium) before being
+printed, such payloads would otherwise execute.
+
+To prevent this, the HTML produced from your Markdown is **sanitized by default**
+with [DOMPurify](https://github.com/cure53/DOMPurify) before it ever reaches the
+browser. Scripts, event handlers, and dangerous URIs (`javascript:`, ...) are
+stripped, while legitimate content — headings, tables, code blocks, images,
+links and KaTeX/MathML/SVG math — is preserved.
+
+If you fully trust the input and need to keep raw HTML (custom `<script>`,
+embeds, etc.), you can opt out:
+
+```bash
+md2pdf trusted.md trusted.pdf --no-sanitize
+```
+
+```js
+await convert({ input: 'trusted.md', output: 'trusted.pdf', sanitize: false });
+```
+
+> Only disable sanitization for content you control. Never run `--no-sanitize`
+> on files from untrusted sources.
+
 ## Programmatic API
 
 ```js
@@ -74,6 +229,11 @@ await convert({
   // css: '/* inline CSS string */',
   format: 'A4',
   pageNumbers: true,
+  sanitize: true,
+  toc: true,
+  tocDepth: 3,
+  highlight: true,
+  codeTheme: 'github-light',
 });
 ```
 
@@ -84,12 +244,22 @@ await convert({
 | `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`)                   |
+| `theme`             | `string`                      | `'default'`            | Built-in theme: `default`/`academic`/`latex`           |
+| `css`               | `string`                      | bundled default        | Inline CSS string (overrides `theme`)                  |
+| `cssFile`           | `string`                      | —                      | Path to a CSS file (overrides `css` and `theme`)       |
 | `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                  |
+| `sanitize`          | `boolean`                     | `true`                 | Sanitize generated HTML (strip scripts/handlers)       |
+| `toc`               | `boolean`                     | `false`                | Prepend an auto-generated table of contents            |
+| `tocDepth`          | `number`                      | `3`                    | Deepest heading level included in the TOC              |
+| `tocTitle`          | `string`                      | `'Contents'`           | TOC heading text                                       |
+| `highlight`         | `boolean`                     | `false`                | Syntax-highlight code blocks with Shiki                |
+| `codeTheme`         | `string`                      | `'github-light'`       | Shiki theme name for code blocks                       |
+| `mermaid`           | `boolean`                     | `false`                | Render `mermaid` code blocks as diagrams               |
+| `mermaidTheme`      | `string`                      | `'base'`               | Mermaid theme name (light by default)                  |
+| `cover`             | `boolean`                     | front matter           | Render a title page (`true`/`false` overrides YAML)    |
 | `headerTemplate`    | `string`                      | empty                  | Puppeteer header HTML                                  |
 | `footerTemplate`    | `string`                      | page numbers           | Puppeteer footer HTML                                  |
 | `puppeteerOptions`  | `object`                      | `{}`                   | Extra options passed to `puppeteer.launch`             |

package/bin/md2pdf.js

@@ -3,6 +3,7 @@
 
 const path = require('path');
 const { convert } = require('../lib/index');
+const { listThemes } = require('../lib/styles');
 
 function printUsage() {
   console.log(`Usage:
@@ -11,9 +12,20 @@ function printUsage() {
 Options:
   --title <text>        Document title (defaults to input filename)
   --css <file>          Path to a custom CSS file (replaces the default styles)
+  --theme <name>        Built-in theme: default, academic, latex
   --format <size>       Page format (A4, Letter, ...). Default: A4
+  --toc                 Prepend an auto-generated table of contents
+  --toc-depth <n>       Max heading level included in the TOC. Default: 3
+  --toc-title <text>    TOC heading text. Default: "Contents"
+  --highlight           Syntax-highlight fenced code blocks (Shiki)
+  --code-theme <name>   Shiki theme for code blocks. Default: github-light
+  --mermaid             Render mermaid fenced code blocks as diagrams
+  --mermaid-theme <t>   Mermaid theme: base, default, neutral, dark, forest. Default: base
+  --cover               Render a title page from YAML front matter
+  --no-cover            Never render a title page (overrides front matter)
   --no-page-numbers     Disable footer page numbers
   --no-math             Disable KaTeX equation rendering ($...$ / $$...$$)
+  --no-sanitize         Disable HTML sanitization (UNSAFE: allows raw HTML/scripts)
   --keep-html           Keep the intermediate .tmp.html file
   -h, --help            Show this help
 
@@ -31,10 +43,21 @@ function parseArgs(argv) {
     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 === '--no-sanitize' || a === '--unsafe') { args.flags.sanitize = false; continue; }
     if (a === '--keep-html') { args.flags.keepHtml = true; continue; }
+    if (a === '--toc') { args.flags.toc = true; continue; }
+    if (a === '--highlight') { args.flags.highlight = true; continue; }
+    if (a === '--mermaid') { args.flags.mermaid = true; continue; }
+    if (a === '--cover') { args.flags.cover = true; continue; }
+    if (a === '--no-cover') { args.flags.cover = false; continue; }
     if (a === '--title') { args.flags.title = argv[++i]; continue; }
     if (a === '--css') { args.flags.cssFile = argv[++i]; continue; }
+    if (a === '--theme') { args.flags.theme = argv[++i]; continue; }
     if (a === '--format') { args.flags.format = argv[++i]; continue; }
+    if (a === '--toc-depth') { args.flags.tocDepth = parseInt(argv[++i], 10); continue; }
+    if (a === '--toc-title') { args.flags.tocTitle = argv[++i]; continue; }
+    if (a === '--code-theme') { args.flags.codeTheme = argv[++i]; continue; }
+    if (a === '--mermaid-theme') { args.flags.mermaidTheme = argv[++i]; continue; }
     if (a.startsWith('--')) {
       console.error(`Unknown option: ${a}`);
       process.exit(2);
@@ -57,15 +80,33 @@ function parseArgs(argv) {
     args.positional[1] ||
     input.replace(/\.md$/i, '') + '.pdf';
 
+  if (args.flags.theme && !listThemes().includes(args.flags.theme)) {
+    console.warn(
+      `WARNING: unknown theme "${args.flags.theme}", falling back to "default". ` +
+        `Available: ${listThemes().join(', ')}`
+    );
+    args.flags.theme = 'default';
+  }
+
   try {
     const result = await convert({
       input,
       output,
       title: args.flags.title,
       cssFile: args.flags.cssFile,
+      theme: args.flags.theme || 'default',
       format: args.flags.format || 'A4',
       pageNumbers: args.flags.pageNumbers !== false,
       math: args.flags.math !== false,
+      sanitize: args.flags.sanitize !== false,
+      toc: !!args.flags.toc,
+      tocDepth: Number.isInteger(args.flags.tocDepth) ? args.flags.tocDepth : 3,
+      tocTitle: args.flags.tocTitle,
+      highlight: !!args.flags.highlight,
+      codeTheme: args.flags.codeTheme,
+      mermaid: !!args.flags.mermaid,
+      mermaidTheme: args.flags.mermaidTheme || 'base',
+      cover: args.flags.cover,
       keepHtml: !!args.flags.keepHtml,
     });
     if (result.brokenImages && result.brokenImages.length) {

package/lib/frontmatter.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const matter = require('gray-matter');
+
+function escapeHtml(s) {
+  return String(s)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+// Splits YAML front matter from the Markdown body. Always returns a plain
+// metadata object and the remaining content (front matter stripped).
+function parseFrontMatter(rawMd) {
+  try {
+    const { data, content } = matter(rawMd);
+    return { data: data && typeof data === 'object' ? data : {}, content };
+  } catch (_) {
+    // Malformed YAML: fall back to treating the whole file as content.
+    return { data: {}, content: rawMd };
+  }
+}
+
+function formatDate(value) {
+  if (value instanceof Date && !isNaN(value)) {
+    return value.toISOString().slice(0, 10);
+  }
+  return String(value);
+}
+
+function normalizeAuthors(data) {
+  const raw = data.author != null ? data.author : data.authors;
+  if (raw == null) return [];
+  return (Array.isArray(raw) ? raw : [raw]).map((a) => String(a)).filter(Boolean);
+}
+
+// Builds a standalone title page from front matter metadata. Returns '' when
+// there is nothing meaningful to show.
+function buildCoverHtml(data = {}) {
+  const parts = [];
+  if (data.title) {
+    parts.push(`<h1 class="cover-title">${escapeHtml(data.title)}</h1>`);
+  }
+  if (data.subtitle) {
+    parts.push(`<p class="cover-subtitle">${escapeHtml(data.subtitle)}</p>`);
+  }
+  const authors = normalizeAuthors(data);
+  if (authors.length) {
+    parts.push(
+      `<p class="cover-author">${authors.map(escapeHtml).join(', ')}</p>`
+    );
+  }
+  if (data.date != null && data.date !== '') {
+    parts.push(`<p class="cover-date">${escapeHtml(formatDate(data.date))}</p>`);
+  }
+  if (!parts.length) return '';
+  return `<section class="cover">${parts.join('')}</section>`;
+}
+
+module.exports = { parseFrontMatter, buildCoverHtml };

package/lib/highlight.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const DEFAULT_THEME = 'github-light';
+
+// Shiki is ESM-only; load it lazily via dynamic import so this CommonJS
+// package keeps working and pays the cost only when highlighting is enabled.
+let shikiPromise = null;
+function loadShiki() {
+  if (!shikiPromise) shikiPromise = import('shiki');
+  return shikiPromise;
+}
+
+// Builds a highlighter preloaded with the requested theme and languages.
+// `codeToHtml` is synchronous once the highlighter exists, so it can safely be
+// called from marked's synchronous `code` renderer.
+async function createCodeHighlighter({ theme = DEFAULT_THEME, langs = [] } = {}) {
+  const shiki = await loadShiki();
+
+  const safeTheme = theme in shiki.bundledThemes ? theme : DEFAULT_THEME;
+  const safeLangs = Array.from(new Set(langs)).filter(
+    (lang) => lang in shiki.bundledLanguages || lang in shiki.bundledLanguagesAlias
+  );
+
+  const highlighter = await shiki.createHighlighter({
+    themes: [safeTheme],
+    langs: safeLangs,
+  });
+  const loaded = new Set(highlighter.getLoadedLanguages());
+
+  return {
+    theme: safeTheme,
+    supports: (lang) => !!lang && loaded.has(lang),
+    toHtml: (code, lang) =>
+      highlighter.codeToHtml(code, { lang, theme: safeTheme }),
+  };
+}
+
+module.exports = { createCodeHighlighter, DEFAULT_THEME };

package/lib/index.js

@@ -2,16 +2,74 @@
 
 const fs = require('fs');
 const path = require('path');
-const { marked } = require('marked');
+const { Marked } = require('marked');
 const markedKatex = require('marked-katex-extension');
 const puppeteer = require('puppeteer');
-const { defaultCss, katexCssLink } = require('./styles');
+const { defaultCss, katexCssLink, getThemeCss } = require('./styles');
+const { sanitizeHtml } = require('./sanitize');
+const { collectHeadings, buildTocHtml, slugify } = require('./toc');
+const { createCodeHighlighter } = require('./highlight');
+const { parseFrontMatter, buildCoverHtml } = require('./frontmatter');
+const { getMermaidScript } = require('./mermaid');
 
-let katexExtensionRegistered = false;
-function ensureKatexExtension() {
-  if (katexExtensionRegistered) return;
-  marked.use(markedKatex({ throwOnError: false, output: 'html', nonStandard: true }));
-  katexExtensionRegistered = true;
+// Recursively collect the fenced-code languages used anywhere in the document
+// (including inside lists/blockquotes) so only those grammars are loaded.
+function collectCodeLangs(tokens, out = new Set()) {
+  for (const token of tokens) {
+    if (token.type === 'code' && token.lang) {
+      out.add(token.lang.trim().split(/\s+/)[0]);
+    }
+    if (token.tokens) collectCodeLangs(token.tokens, out);
+    if (token.items) collectCodeLangs(token.items, out);
+    if (token.rows) for (const row of token.rows) collectCodeLangs(row, out);
+  }
+  return out;
+}
+
+// Render Markdown to HTML using an isolated Marked instance so per-call state
+// (heading ids, KaTeX extension, highlighter) never leaks across invocations.
+async function renderMarkdown({ md, math, toc, tocDepth, tocTitle, highlight, codeTheme, mermaid }) {
+  const m = new Marked();
+  m.setOptions({ gfm: true, breaks: false });
+  if (math) {
+    m.use(markedKatex({ throwOnError: false, output: 'html', nonStandard: true }));
+  }
+
+  const tokens = m.lexer(md);
+  const headings = collectHeadings(tokens);
+  const slugs = headings.map((h) => h.slug);
+
+  let highlighter = null;
+  if (highlight) {
+    const langs = Array.from(collectCodeLangs(tokens));
+    highlighter = await createCodeHighlighter({ theme: codeTheme, langs });
+  }
+
+  let idx = 0;
+  const renderer = {
+    heading(text, level) {
+      const slug = slugs[idx++] || slugify(text) || `section-${idx}`;
+      return `<h${level} id="${slug}">${text}</h${level}>\n`;
+    },
+  };
+  if (highlighter || mermaid) {
+    renderer.code = (text, infostring) => {
+      const lang = (infostring || '').trim().split(/\s+/)[0];
+      if (mermaid && lang === 'mermaid') {
+        return `<pre class="mermaid">${escapeHtml(text)}</pre>\n`;
+      }
+      if (highlighter && highlighter.supports(lang)) {
+        return highlighter.toHtml(text, lang);
+      }
+      const cls = lang ? ` class="language-${lang}"` : '';
+      return `<pre><code${cls}>${escapeHtml(text)}</code></pre>\n`;
+    };
+  }
+  m.use({ renderer });
+
+  const body = m.parse(md);
+  const tocHtml = toc ? buildTocHtml(headings, { title: tocTitle, depth: tocDepth }) : '';
+  return { body, tocHtml };
 }
 
 function buildHtml({ body, title, css, math }) {
@@ -97,6 +155,16 @@ async function convert(options) {
     puppeteerOptions = {},
     keepHtml = false,
     math = true,
+    sanitize = true,
+    toc = false,
+    tocDepth = 3,
+    tocTitle = 'Contents',
+    highlight = false,
+    codeTheme = 'github-light',
+    cover,
+    theme = 'default',
+    mermaid = false,
+    mermaidTheme = 'base',
   } = options;
 
   if (!input) throw new Error('`input` is required');
@@ -110,17 +178,36 @@ async function convert(options) {
   }
 
   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);
+  const { data: frontMatter, content } = parseFrontMatter(rawMd);
+  const md = math ? normalizeBlockMath(content) : content;
+  const { body: parsedBody, tocHtml } = await renderMarkdown({
+    md,
+    math,
+    toc,
+    tocDepth,
+    tocTitle,
+    highlight,
+    codeTheme,
+    mermaid,
+  });
+
+  const wantCover =
+    cover === true || (cover == null && frontMatter.cover === true);
+  const coverHtml = wantCover ? buildCoverHtml(frontMatter) : '';
+  const fullBody = [coverHtml, tocHtml, parsedBody].filter(Boolean).join('\n');
+  const body = sanitize ? sanitizeHtml(fullBody) : fullBody;
 
-  let resolvedCss = css || defaultCss;
+  let resolvedCss;
   if (cssFile) {
     resolvedCss = fs.readFileSync(path.resolve(cssFile), 'utf8');
+  } else if (css) {
+    resolvedCss = css;
+  } else {
+    resolvedCss = getThemeCss(theme);
   }
 
-  const docTitle = title || path.basename(inputAbs, path.extname(inputAbs));
+  const docTitle =
+    title || frontMatter.title || path.basename(inputAbs, path.extname(inputAbs));
   const html = buildHtml({ body, title: docTitle, css: resolvedCss, math });
 
   const tmpHtmlPath = outputAbs.replace(/\.pdf$/i, '') + '.tmp.html';
@@ -154,6 +241,21 @@ async function convert(options) {
         .map((img) => img.src)
     );
 
+    if (mermaid && (await page.$('.mermaid'))) {
+      await page.addScriptTag({ content: getMermaidScript() });
+      await page.evaluate(async (themeName) => {
+        window.mermaid.initialize({
+          startOnLoad: false,
+          securityLevel: 'strict',
+          theme: themeName,
+        });
+        await window.mermaid.run({
+          querySelector: '.mermaid',
+          suppressErrors: true,
+        });
+      }, mermaidTheme);
+    }
+
     const pdfOptions = {
       path: outputAbs,
       format,
@@ -181,4 +283,4 @@ async function convert(options) {
   }
 }
 
-module.exports = { convert, defaultCss };
+module.exports = { convert, defaultCss, renderMarkdown };

package/lib/mermaid.js

@@ -0,0 +1,16 @@
+'use strict';
+
+const fs = require('fs');
+
+// Mermaid's bundled UMD build is large (~3 MB); read it lazily and cache it so
+// it is only loaded into memory when a document actually uses diagrams.
+let cachedScript = null;
+
+function getMermaidScript() {
+  if (cachedScript != null) return cachedScript;
+  const scriptPath = require.resolve('mermaid/dist/mermaid.min.js');
+  cachedScript = fs.readFileSync(scriptPath, 'utf8');
+  return cachedScript;
+}
+
+module.exports = { getMermaidScript };

package/lib/sanitize.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const { JSDOM } = require('jsdom');
+const createDOMPurify = require('dompurify');
+
+let purifier = null;
+
+function getPurifier() {
+  if (purifier) return purifier;
+  const { window } = new JSDOM('');
+  purifier = createDOMPurify(window);
+  return purifier;
+}
+
+function sanitizeHtml(html) {
+  const DOMPurify = getPurifier();
+  return DOMPurify.sanitize(html, {
+    USE_PROFILES: { html: true, svg: true, svgFilters: true, mathMl: true },
+    ADD_ATTR: ['target'],
+    FORBID_TAGS: ['style'],
+    ALLOW_DATA_ATTR: false,
+  });
+}
+
+module.exports = { sanitizeHtml };

package/lib/styles.js

@@ -13,22 +13,72 @@ function katexCssLink() {
   return `<link rel="stylesheet" href="${fileUrl}">`;
 }
 
-const defaultCss = `
+// Structural rules required by the converter's features (KaTeX, TOC, cover
+// page, images, page-break safety). These are theme-agnostic and always
+// applied; per-theme skins below only handle typography and colors.
+const baseCss = `
 @page { size: A4; margin: 22mm 18mm 22mm 18mm; }
 * { box-sizing: border-box; }
+body { margin: 0; max-width: 100%; }
+h1, h2, h3, h4 { page-break-after: avoid; break-after: avoid; }
+img {
+  max-width: 100%;
+  height: auto;
+  display: block;
+  margin: 12px auto;
+  page-break-inside: avoid;
+  break-inside: avoid;
+}
+table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 12px 0 18px 0;
+  page-break-inside: avoid;
+}
+pre { overflow-x: auto; page-break-inside: avoid; }
+.mermaid {
+  text-align: center;
+  margin: 14px 0;
+  background: #ffffff;
+  color: #000;
+  padding: 8px 0;
+  border: none;
+  page-break-inside: avoid;
+  break-inside: avoid;
+}
+.mermaid svg { max-width: 100%; height: auto; background: #ffffff; }
+.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%; }
+nav.toc { page-break-after: always; break-after: page; margin-bottom: 8px; }
+nav.toc .toc-title { margin-top: 0; padding-bottom: 4px; }
+nav.toc ul { list-style: none; margin: 4px 0; padding-left: 18px; }
+nav.toc > ul { padding-left: 0; }
+nav.toc li { margin-bottom: 3px; }
+section.cover {
+  page-break-after: always;
+  break-after: page;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  min-height: 80vh;
+}
+section.cover .cover-title { font-size: 30pt; border: none; margin: 0 0 8px 0; padding: 0; }
+section.cover .cover-subtitle { font-size: 15pt; margin: 0 0 28px 0; }
+section.cover .cover-author { font-size: 13pt; margin: 0 0 6px 0; }
+section.cover .cover-date { font-size: 11pt; margin: 0; }
+`;
+
+const defaultSkin = `
 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, h2, h3, h4 { color: #102a43; }
 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; }
@@ -45,59 +95,119 @@ code {
   font-size: 9.5pt;
   color: #b91c1c;
 }
-pre {
-  background: #0f172a;
-  color: #f1f5f9;
-  padding: 12px;
-  border-radius: 5px;
-  overflow-x: auto;
-  font-size: 9pt;
-}
+pre { background: #0f172a; color: #f1f5f9; padding: 12px; border-radius: 5px; 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;
-}
+table { 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;
+blockquote { border-left: 4px solid #64748b; padding: 4px 12px; color: #475569; background: #f8fafc; margin: 10px 0; }
+img { border: 1px solid #e2e8f0; border-radius: 4px; }
+img + em, p > em { display: block; text-align: center; color: #475569; font-size: 9.5pt; margin-bottom: 14px; }
+a { color: #1d4ed8; text-decoration: none; }
+nav.toc .toc-title { border-bottom: 1px solid #bcccdc; }
+nav.toc a { color: #102a43; }
+section.cover .cover-subtitle { color: #475569; }
+section.cover .cover-author { color: #102a43; }
+section.cover .cover-date { color: #64748b; }
+`;
+
+// Emulates the classic LaTeX `article` look: Computer Modern serif, justified
+// and indented paragraphs, booktabs-style rules, centered title.
+const latexSkin = `
+body {
+  font-family: "Latin Modern Roman", "CMU Serif", "Computer Modern", "Georgia", "Times New Roman", serif;
+  font-size: 11pt;
+  line-height: 1.5;
+  color: #000;
 }
-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;
+h1, h2, h3, h4 { color: #000; font-weight: 700; }
+h1 { font-size: 19pt; text-align: center; margin-top: 0; margin-bottom: 20px; }
+h2 { font-size: 14pt; margin-top: 24px; }
+h3 { font-size: 12pt; margin-top: 18px; }
+h4 { font-size: 11pt; margin-top: 14px; font-style: italic; font-weight: 600; }
+p { text-align: justify; margin: 0 0 2px 0; text-indent: 1.5em; }
+p:first-of-type, h1 + p, h2 + p, h3 + p, h4 + p { text-indent: 0; }
+ul, ol { margin: 6px 0 10px 0; padding-left: 24px; }
+li { margin-bottom: 2px; }
+code {
+  background: #f4f4f4;
+  padding: 1px 4px;
+  border-radius: 2px;
+  font-family: "Consolas", "Courier New", monospace;
+  font-size: 9.5pt;
+  color: #222;
 }
-img + em, p > em {
-  display: block;
-  text-align: center;
-  color: #475569;
+pre { background: #f4f4f4; color: #1a1a1a; padding: 12px; border: 1px solid #ddd; border-radius: 3px; font-size: 9pt; }
+pre code { background: transparent; color: inherit; padding: 0; }
+table { font-size: 10pt; margin: 14px auto; border-top: 1.5px solid #000; border-bottom: 1.5px solid #000; }
+th, td { border: none; padding: 5px 12px; text-align: left; vertical-align: top; }
+th { border-bottom: 1px solid #000; font-weight: 700; }
+hr { border: none; border-top: 1px solid #000; margin: 22px 0; }
+blockquote { border-left: 2px solid #000; padding: 2px 14px; color: #1a1a1a; margin: 10px 24px; }
+img + em, p > em { display: block; text-align: center; color: #333; font-size: 9.5pt; margin-bottom: 14px; }
+a { color: #000; text-decoration: none; }
+nav.toc .toc-title { border-bottom: 1px solid #000; text-align: center; }
+nav.toc a { color: #000; }
+section.cover .cover-subtitle { color: #333; }
+section.cover .cover-date { color: #333; }
+`;
+
+const academicSkin = `
+body {
+  font-family: "Georgia", "Times New Roman", "Cambria", serif;
+  font-size: 11.5pt;
+  line-height: 1.6;
+  color: #161616;
+}
+h1, h2, h3, h4 { color: #161616; font-weight: 700; font-family: "Georgia", "Times New Roman", serif; }
+h1 { font-size: 20pt; text-align: center; margin-top: 0; margin-bottom: 18px; }
+h2 { font-size: 15pt; margin-top: 26px; }
+h3 { font-size: 12.5pt; margin-top: 20px; font-style: italic; }
+h4 { font-size: 11.5pt; margin-top: 16px; }
+p { text-align: justify; margin: 0 0 4px 0; text-indent: 1.6em; }
+p:first-of-type, h1 + p, h2 + p, h3 + p, h4 + p { text-indent: 0; }
+ul, ol { margin: 8px 0 12px 0; padding-left: 26px; }
+li { margin-bottom: 3px; }
+code {
+  background: #f2f2f0;
+  padding: 1px 4px;
+  border-radius: 2px;
+  font-family: "Consolas", "Courier New", monospace;
   font-size: 9.5pt;
-  margin-bottom: 14px;
+  color: #333;
 }
-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%; }
+pre { background: #f2f2f0; color: #1a1a1a; padding: 12px; border: 1px solid #ddd; border-radius: 3px; font-size: 9pt; }
+pre code { background: transparent; color: inherit; padding: 0; }
+table { font-size: 10pt; margin: 14px auto; }
+th, td { border: 1px solid #999; padding: 5px 10px; text-align: left; vertical-align: top; }
+th { background: #ececec; font-weight: 700; }
+hr { border: none; border-top: 1px solid #999; margin: 22px 0; }
+blockquote { border-left: 3px solid #888; padding: 2px 14px; color: #333; font-style: italic; margin: 10px 20px; }
+img + em, p > em { display: block; text-align: center; color: #444; font-size: 9.5pt; margin-bottom: 14px; }
+a { color: #1a1a1a; text-decoration: underline; }
+nav.toc .toc-title { border-bottom: 1px solid #999; text-align: center; }
+nav.toc a { color: #161616; }
+section.cover .cover-subtitle { color: #444; font-style: italic; }
+section.cover .cover-date { color: #555; }
 `;
 
-module.exports = { defaultCss, katexCssLink };
+const themes = {
+  default: defaultSkin,
+  academic: academicSkin,
+  latex: latexSkin,
+};
+
+function listThemes() {
+  return Object.keys(themes);
+}
+
+function getThemeCss(name) {
+  const skin = themes[name] || themes.default;
+  return `${baseCss}\n${skin}`;
+}
+
+const defaultCss = getThemeCss('default');
+
+module.exports = { defaultCss, katexCssLink, getThemeCss, listThemes };

package/lib/toc.js

@@ -0,0 +1,75 @@
+'use strict';
+
+function escapeHtml(s) {
+  return String(s)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function slugify(text) {
+  return String(text)
+    .toLowerCase()
+    .trim()
+    .replace(/<[^>]*>/g, '')
+    .replace(/[^\w\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function collectHeadings(tokens) {
+  const used = new Map();
+  const out = [];
+  for (const token of tokens) {
+    if (token.type !== 'heading') continue;
+    const text = token.text;
+    let slug = slugify(text) || 'section';
+    if (used.has(slug)) {
+      const next = used.get(slug) + 1;
+      used.set(slug, next);
+      slug = `${slug}-${next}`;
+    } else {
+      used.set(slug, 0);
+    }
+    out.push({ level: token.depth, text, slug });
+  }
+  return out;
+}
+
+function nest(items) {
+  const root = { level: -Infinity, children: [] };
+  const stack = [root];
+  for (const item of items) {
+    const node = { ...item, children: [] };
+    while (stack.length > 1 && stack[stack.length - 1].level >= item.level) {
+      stack.pop();
+    }
+    stack[stack.length - 1].children.push(node);
+    stack.push(node);
+  }
+  return root.children;
+}
+
+function renderNodes(nodes) {
+  if (!nodes.length) return '';
+  const items = nodes
+    .map(
+      (n) =>
+        `<li><a href="#${n.slug}">${escapeHtml(n.text)}</a>${renderNodes(n.children)}</li>`
+    )
+    .join('');
+  return `<ul>${items}</ul>`;
+}
+
+function buildTocHtml(headings, { title = 'Contents', depth = 3 } = {}) {
+  const items = headings.filter((h) => h.level <= depth);
+  if (!items.length) return '';
+  const heading = title
+    ? `<h2 class="toc-title">${escapeHtml(title)}</h2>`
+    : '';
+  return `<nav class="toc">${heading}${renderNodes(nest(items))}</nav>`;
+}
+
+module.exports = { slugify, collectHeadings, buildTocHtml };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brahim.ariani/md2pdf-cli",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Convert Markdown files to beautifully styled PDFs using marked and puppeteer.",
   "keywords": [
     "markdown",
@@ -31,13 +31,24 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node test/smoke.js"
+    "test": "node test/sanitize.js && node test/toc.js && node test/highlight.js && node test/frontmatter.js && node test/themes.js && node test/mermaid.js && node test/smoke.js",
+    "test:sanitize": "node test/sanitize.js",
+    "test:toc": "node test/toc.js",
+    "test:highlight": "node test/highlight.js",
+    "test:frontmatter": "node test/frontmatter.js",
+    "test:themes": "node test/themes.js",
+    "test:mermaid": "node test/mermaid.js"
   },
   "dependencies": {
+    "dompurify": "^3.4.7",
+    "gray-matter": "^4.0.3",
+    "jsdom": "^29.1.1",
     "katex": "^0.16.9",
     "marked": "^12.0.0",
     "marked-katex-extension": "^5.0.0",
-    "puppeteer": "^24.15.0"
+    "mermaid": "^11.15.0",
+    "puppeteer": "^24.15.0",
+    "shiki": "^4.1.0"
   },
   "repository": {
     "type": "git",