md-pdf-studio 2.2.0 → 2.4.0

package/src/core/epub.js

@@ -0,0 +1,338 @@
+/*! 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');
+const { readLocalImage } = require('./images');
+const { createZip } = require('./zip');
+
+/**
+ * Markdown to EPUB 3, written from the document model. Every page is XHTML
+ * serialized here, so it is well formed whatever raw HTML the Markdown holds.
+ *
+ * The book is split into one file per top-level heading, with a navigation
+ * document (and an NCX for older readers) built from the headings. Local
+ * images are embedded; an image on the web is replaced by a link to it, since
+ * a reader may be offline. Themes, custom CSS, Mermaid and KaTeX are not
+ * carried over: a reading system applies its own typography.
+ */
+
+function xml(text) {
+  return String(text)
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F￾￿]/g, '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+const STYLESHEET = `body { font-family: serif; line-height: 1.5; margin: 0 5%; }
+h1, h2, h3, h4, h5, h6 { font-family: sans-serif; line-height: 1.25; page-break-after: avoid; }
+h1 { font-size: 1.8em; margin-top: 1.5em; }
+h2 { font-size: 1.4em; }
+h3 { font-size: 1.2em; }
+p { margin: 0.6em 0; }
+a { color: #0b57d0; }
+img { max-width: 100%; height: auto; }
+code { font-family: monospace; font-size: 0.9em; background: #f2f2f2; padding: 0.1em 0.25em; }
+pre { background: #f5f5f5; padding: 0.8em; white-space: pre-wrap; word-wrap: break-word; font-size: 0.85em; }
+pre code { background: none; padding: 0; font-size: 1em; }
+blockquote { margin: 0.8em 0; padding-left: 1em; border-left: 0.25em solid #bfbfbf; color: #595959; }
+table { border-collapse: collapse; margin: 0.8em 0; width: 100%; }
+th, td { border: 1px solid #bfbfbf; padding: 0.3em 0.5em; text-align: left; vertical-align: top; }
+th { background: #f2f2f2; }
+hr { border: 0; border-top: 1px solid #bfbfbf; margin: 1.5em 0; }
+ul.tasks { list-style: none; padding-left: 1.2em; }
+.page-break { page-break-after: always; }
+.cover { text-align: center; margin-top: 30%; }
+.cover h1 { font-size: 2.2em; }
+.cover .subtitle { font-size: 1.3em; color: #595959; }
+.cover .line { color: #595959; }
+nav ol { list-style: none; padding-left: 1.2em; }
+.hljs-comment, .hljs-quote { color: #6a737d; }
+.hljs-keyword, .hljs-selector-tag, .hljs-literal, .hljs-type { color: #d73a49; }
+.hljs-string, .hljs-regexp, .hljs-attr, .hljs-addition { color: #22863a; }
+.hljs-number, .hljs-built_in, .hljs-symbol, .hljs-meta { color: #005cc5; }
+.hljs-title, .hljs-section, .hljs-name, .hljs-function { color: #6f42c1; }
+.hljs-deletion { color: #b31d28; }
+`;
+
+class EpubWriter {
+  constructor(document, baseDir) {
+    this.document = document;
+    this.baseDir = baseDir;
+    this.images = [];
+    this.imagePaths = new Map();
+    // Where each heading ends up, so a link to `#slug` can name the right file.
+    this.targets = new Map();
+  }
+
+  image(run) {
+    const { src, alt } = run.image;
+    if (!this.imagePaths.has(src)) {
+      const image = readLocalImage(src, this.baseDir);
+      if (image) {
+        const name = `images/image-${this.images.length + 1}.${image.extension}`;
+        this.images.push({ name, data: image.data, mediaType: image.mediaType });
+        this.imagePaths.set(src, name);
+      } else {
+        this.imagePaths.set(src, null);
+      }
+    }
+    const path = this.imagePaths.get(src);
+    if (path) return `<img src="${xml(path)}" alt="${xml(alt)}"/>`;
+    // Not a local file: a link stands in for it when it has a web address.
+    const label = xml(alt || src);
+    return /^https?:\/\//i.test(src) ? `<a href="${xml(src)}">${label}</a>` : `<em>[${label}]</em>`;
+  }
+
+  /** The address a link is written with, or null when it would lead nowhere from inside the book. */
+  href(target) {
+    if (target[0] !== '#') return isPortableLink(target) ? target : null;
+    let id = target.slice(1);
+    try {
+      id = decodeURIComponent(id);
+    } catch (_) {
+      // Used as written.
+    }
+    const file = this.targets.get(id);
+    return file ? `${file}#${encodeURIComponent(id)}` : null;
+  }
+
+  runs(runs) {
+    return runs
+      .map(run => {
+        let html;
+        if (run.lineBreak) return '<br/>';
+        if (run.image) html = this.image(run);
+        else html = xml(run.text);
+        if (run.code) html = `<code>${html}</code>`;
+        if (run.sup) html = `<sup>${html}</sup>`;
+        else if (run.sub) html = `<sub>${html}</sub>`;
+        if (run.strike) html = `<del>${html}</del>`;
+        if (run.italic) html = `<em>${html}</em>`;
+        if (run.bold) html = `<strong>${html}</strong>`;
+        const href = run.href ? this.href(run.href) : null;
+        // An image that already became a link is not wrapped in a second one.
+        if (href && !html.startsWith('<a ')) html = `<a href="${xml(href)}">${html}</a>`;
+        return html;
+      })
+      .join('');
+  }
+
+  code(block) {
+    const highlight = this.document.settings.highlight && block.lang && hljs.getLanguage(block.lang);
+    // highlight.js escapes the code and adds only balanced spans, so its output is XHTML too.
+    const body = highlight ? hljs.highlight(block.text, { language: block.lang, ignoreIllegals: true }).value : xml(block.text);
+    return `<pre><code>${body}</code></pre>\n`;
+  }
+
+  blocks(blocks) {
+    let output = '';
+    for (const block of blocks) {
+      switch (block.type) {
+        case 'heading': {
+          const tag = `h${Math.min(block.depth, 6)}`;
+          output += `<${tag} id="${xml(block.id)}">${this.runs(block.runs)}</${tag}>\n`;
+          break;
+        }
+        case 'paragraph':
+          output += `<p>${this.runs(block.runs)}</p>\n`;
+          break;
+        case 'code':
+          output += this.code(block);
+          break;
+        case 'quote':
+          output += `<blockquote>\n${this.blocks(block.blocks) || '<p></p>\n'}</blockquote>\n`;
+          break;
+        case 'list': {
+          const tasks = block.items.some(item => item.checked !== null);
+          const tag = block.ordered ? 'ol' : 'ul';
+          const attributes = block.ordered && block.start !== 1 ? ` start="${block.start}"` : !block.ordered && tasks ? ' class="tasks"' : '';
+          const items = block.items.map(item => {
+            const box = item.checked === null ? '' : item.checked ? '☑ ' : '☐ ';
+            // A tight item is one line of text: no paragraph around it.
+            const single = item.blocks.length === 1 && item.blocks[0].type === 'paragraph';
+            const body = single ? box + this.runs(item.blocks[0].runs) : box + this.blocks(item.blocks);
+            return `<li>${body}</li>\n`;
+          });
+          output += `<${tag}${attributes}>\n${items.join('') || '<li></li>\n'}</${tag}>\n`;
+          break;
+        }
+        case 'table': {
+          const cell = (tag, source) => {
+            const align = source.align && source.align !== 'left' ? ` style="text-align: ${source.align}"` : '';
+            return `<${tag}${align}>${this.runs(source.runs)}</${tag}>`;
+          };
+          output +=
+            `<table>\n<thead>\n<tr>${block.header.map(source => cell('th', source)).join('')}</tr>\n</thead>\n` +
+            (block.rows.length
+              ? `<tbody>\n${block.rows.map(row => `<tr>${row.map(source => cell('td', source)).join('')}</tr>\n`).join('')}</tbody>\n`
+              : '') +
+            '</table>\n';
+          break;
+        }
+        case 'rule':
+          output += '<hr/>\n';
+          break;
+        case 'pageBreak':
+          output += '<div class="page-break"></div>\n';
+          break;
+        default:
+          break;
+      }
+    }
+    return output;
+  }
+
+  page(title, body, bodyAttributes = '') {
+    const language = xml(this.document.meta.language);
+    return (
+      '<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE html>\n' +
+      `<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" lang="${language}" xml:lang="${language}">\n` +
+      `<head>\n<meta charset="UTF-8"/>\n<title>${xml(title)}</title>\n<link rel="stylesheet" type="text/css" href="style.css"/>\n</head>\n` +
+      `<body${bodyAttributes}>\n${body}</body>\n</html>\n`
+    );
+  }
+
+  /** The blocks cut into chapters: a new one at every top-level heading. */
+  chapters() {
+    const { blocks, meta } = this.document;
+    const chapters = [];
+    for (const block of blocks) {
+      const opens = block.type === 'heading' && block.depth === 1;
+      if (opens || chapters.length === 0) {
+        chapters.push({ title: opens ? plainText(block.runs) : meta.title, blocks: [] });
+      }
+      chapters[chapters.length - 1].blocks.push(block);
+    }
+    if (chapters.length === 0) chapters.push({ title: meta.title, blocks: [] });
+    chapters.forEach((chapter, index) => {
+      chapter.file = `chapter-${index + 1}.xhtml`;
+      for (const heading of collectHeadings(chapter.blocks)) this.targets.set(heading.id, chapter.file);
+    });
+    return chapters;
+  }
+
+  /** Headings up to the third level as a nested list of { title, href, children }. */
+  outline(chapters) {
+    const root = { depth: 0, children: [] };
+    const stack = [root];
+    for (const chapter of chapters) {
+      const headings = collectHeadings(chapter.blocks).filter(heading => heading.depth <= 3);
+      // A chapter that opens with no heading still has to be reachable.
+      if (!headings.length || chapter.blocks[0] !== headings[0]) {
+        stack.length = 1;
+        const entry = { depth: 1, title: chapter.title, href: chapter.file, children: [] };
+        root.children.push(entry);
+        stack.push(entry);
+      }
+      for (const heading of headings) {
+        while (stack[stack.length - 1].depth >= heading.depth) stack.pop();
+        const entry = { depth: heading.depth, title: plainText(heading.runs) || 'Untitled', href: `${chapter.file}#${encodeURIComponent(heading.id)}`, children: [] };
+        stack[stack.length - 1].children.push(entry);
+        stack.push(entry);
+      }
+    }
+    return root.children;
+  }
+
+  build(now = new Date()) {
+    const { meta, settings } = this.document;
+    const chapters = this.chapters();
+    const outline = this.outline(chapters);
+    const pages = chapters.map(chapter => ({ name: chapter.file, data: this.page(chapter.title, this.blocks(chapter.blocks)) }));
+
+    const navList = entries =>
+      `<ol>\n${entries
+        .map(entry => `<li><a href="${xml(entry.href)}">${xml(entry.title)}</a>${entry.children.length ? `\n${navList(entry.children)}` : ''}</li>\n`)
+        .join('')}</ol>\n`;
+    const nav = this.page(
+      'Table of Contents',
+      `<nav epub:type="toc" id="toc">\n<h1>Table of Contents</h1>\n${navList(outline)}</nav>\n`
+    );
+
+    let playOrder = 0;
+    const navPoints = entries =>
+      entries
+        .map(entry => {
+          const order = ++playOrder;
+          return (
+            `<navPoint id="nav-${order}" playOrder="${order}"><navLabel><text>${xml(entry.title)}</text></navLabel>` +
+            `<content src="${xml(entry.href)}"/>${navPoints(entry.children)}</navPoint>\n`
+          );
+        })
+        .join('');
+    const identifier = `urn:uuid:${crypto.randomUUID()}`;
+    const ncx =
+      '<?xml version="1.0" encoding="UTF-8"?>\n<ncx xmlns="http://www.daisy.org/z3986/2005/ncx/" version="2005-1">\n' +
+      `<head><meta name="dtb:uid" content="${identifier}"/><meta name="dtb:depth" content="3"/>` +
+      '<meta name="dtb:totalPageCount" content="0"/><meta name="dtb:maxPageNumber" content="0"/></head>\n' +
+      `<docTitle><text>${xml(meta.title)}</text></docTitle>\n<navMap>\n${navPoints(outline)}</navMap>\n</ncx>\n`;
+
+    let cover = null;
+    if (settings.cover) {
+      cover = this.page(
+        meta.title,
+        `<div class="cover">\n<h1>${xml(meta.title)}</h1>\n` +
+          (meta.subtitle ? `<p class="subtitle">${xml(meta.subtitle)}</p>\n` : '') +
+          [meta.author, meta.date].filter(Boolean).map(line => `<p class="line">${xml(line)}</p>\n`).join('') +
+          '</div>\n'
+      );
+    }
+
+    const manifest = [
+      '<item id="nav" href="nav.xhtml" media-type="application/xhtml+xml" properties="nav"/>',
+      '<item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml"/>',
+      '<item id="css" href="style.css" media-type="text/css"/>',
+      ...(cover ? ['<item id="cover" href="cover.xhtml" media-type="application/xhtml+xml"/>'] : []),
+      ...pages.map((page, index) => `<item id="chapter-${index + 1}" href="${page.name}" media-type="application/xhtml+xml"/>`),
+      ...this.images.map((image, index) => `<item id="image-${index + 1}" href="${xml(image.name)}" media-type="${image.mediaType}"/>`)
+    ];
+    const spine = [
+      ...(cover ? ['<itemref idref="cover"/>'] : []),
+      // The contents page is always in the book for the reader's own menu; it is a page to read only when asked for.
+      ...(settings.toc ? ['<itemref idref="nav"/>'] : []),
+      ...pages.map((_, index) => `<itemref idref="chapter-${index + 1}"/>`)
+    ];
+    const opf =
+      '<?xml version="1.0" encoding="UTF-8"?>\n' +
+      '<package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="book-id">\n' +
+      '<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">\n' +
+      `<dc:identifier id="book-id">${identifier}</dc:identifier>\n<dc:title>${xml(meta.title)}</dc:title>\n` +
+      `<dc:language>${xml(meta.language)}</dc:language>\n` +
+      (meta.author ? `<dc:creator>${xml(meta.author)}</dc:creator>\n` : '') +
+      `<meta property="dcterms:modified">${now.toISOString().replace(/\.\d+Z$/, 'Z')}</meta>\n</metadata>\n` +
+      `<manifest>\n${manifest.join('\n')}\n</manifest>\n<spine toc="ncx">\n${spine.join('\n')}\n</spine>\n</package>\n`;
+    const container =
+      '<?xml version="1.0" encoding="UTF-8"?>\n' +
+      '<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">\n' +
+      '<rootfiles><rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/></rootfiles>\n</container>\n';
+
+    return createZip([
+      // First and uncompressed: it is how a reader recognizes the file.
+      { name: 'mimetype', data: 'application/epub+zip', store: true },
+      { name: 'META-INF/container.xml', data: container },
+      { name: 'OEBPS/content.opf', data: opf },
+      { name: 'OEBPS/nav.xhtml', data: nav },
+      { name: 'OEBPS/toc.ncx', data: ncx },
+      { name: 'OEBPS/style.css', data: STYLESHEET },
+      ...(cover ? [{ name: 'OEBPS/cover.xhtml', data: cover }] : []),
+      ...pages.map(page => ({ name: `OEBPS/${page.name}`, data: page.data })),
+      ...this.images.map(image => ({ name: `OEBPS/${image.name}`, data: image.data, store: true }))
+    ]);
+  }
+}
+
+/**
+ * Converts Markdown to the bytes of an .epub file.
+ * @param {string} rawMarkdown
+ * @param {Object} [options] The converter's options, plus `baseDir`: the folder images are relative to
+ * @returns {Buffer}
+ */
+function markdownToEpub(rawMarkdown, options = {}) {
+  return new EpubWriter(buildDocument(rawMarkdown, options), options.baseDir).build();
+}
+
+module.exports = {
+  markdownToEpub
+};

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

@@ -0,0 +1,70 @@
+/*! 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');
+
+/**
+ * Local images for the exporters that embed them (DOCX, EPUB).
+ */
+
+const MEDIA_TYPES = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  svg: 'image/svg+xml',
+  webp: 'image/webp'
+};
+
+/**
+ * Width and height in pixels of a PNG, JPEG or GIF, read from its header.
+ * @param {Buffer} data
+ * @returns {{ width: number, height: number } | null} null for anything else
+ */
+function imageSize(data) {
+  if (data.length >= 24 && data.readUInt32BE(0) === 0x89504e47 && data.toString('ascii', 12, 16) === 'IHDR') {
+    return { width: data.readUInt32BE(16), height: data.readUInt32BE(20) };
+  }
+  if (data.length >= 10 && data.toString('ascii', 0, 3) === 'GIF') {
+    return { width: data.readUInt16LE(6), height: data.readUInt16LE(8) };
+  }
+  if (data.length >= 4 && data[0] === 0xff && data[1] === 0xd8) {
+    let offset = 2;
+    while (offset + 9 < data.length) {
+      if (data[offset] !== 0xff) return null;
+      const marker = data[offset + 1];
+      // Start-of-frame markers carry the size; C4, C8 and CC are other tables.
+      if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+        return { width: data.readUInt16BE(offset + 7), height: data.readUInt16BE(offset + 5) };
+      }
+      offset += 2 + data.readUInt16BE(offset + 2);
+    }
+  }
+  return null;
+}
+
+/**
+ * Reads the image a Markdown document refers to.
+ * @param {string} src As written in the document
+ * @param {string} baseDir Folder of the document
+ * @returns {{ data: Buffer, extension: string, mediaType: string, size: { width: number, height: number } | null } | null}
+ *   null when it is not a readable local file of a known type (a web address, for one)
+ */
+function readLocalImage(src, baseDir) {
+  if (!src || /^[a-z][a-z0-9+.-]*:/i.test(src) && !/^file:/i.test(src) && !/^[a-zA-Z]:[\\/]/.test(src)) return null;
+  let relative = src.replace(/^file:\/\/\/?/i, '').split(/[?#]/)[0];
+  try {
+    relative = decodeURIComponent(relative);
+  } catch (_) {
+    // A stray percent sign: the name is used as written.
+  }
+  const filePath = path.resolve(baseDir || process.cwd(), relative);
+  const extension = path.extname(filePath).slice(1).toLowerCase();
+  if (!MEDIA_TYPES[extension] || !fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) return null;
+  const data = fs.readFileSync(filePath);
+  return { data, extension: extension === 'jpeg' ? 'jpg' : extension, mediaType: MEDIA_TYPES[extension], size: imageSize(data) };
+}
+
+module.exports = {
+  imageSize,
+  readLocalImage
+};

package/src/core/include.js

@@ -0,0 +1,105 @@
+/*! 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');
+
+/**
+ * File includes: a line that holds only `@import "path"` is replaced by the
+ * file it names, relative to the file the line is in.
+ *
+ * A Markdown file (.md, .markdown) is put in as Markdown, without its front
+ * matter, and may import further files itself. Any other file is put in as a
+ * fenced code block labelled with its extension, so `@import "src/app.js"`
+ * shows the source. Lines inside a fenced code block are left as they are.
+ */
+
+const IMPORT_LINE = /^[ \t]*@import[ \t]+(["'])(.+?)\1[ \t]*$/;
+const FENCE_LINE = /^ {0,3}(`{3,}|~{3,})/;
+const MARKDOWN_EXTENSIONS = new Set(['.md', '.markdown']);
+const MAX_DEPTH = 10;
+
+/**
+ * A fence longer than any run of backticks in the code, so the code cannot
+ * close its own block.
+ * @param {string} code
+ * @returns {string}
+ */
+function fenceFor(code) {
+  const longest = (code.match(/`+/g) || []).reduce((max, run) => Math.max(max, run.length), 0);
+  return '`'.repeat(Math.max(3, longest + 1));
+}
+
+function expand(markdown, filePath, chain, files) {
+  const baseDir = path.dirname(filePath);
+  const output = [];
+  let fence = null;
+
+  markdown.split(/\r?\n/).forEach((line, index) => {
+    const fenceMatch = line.match(FENCE_LINE);
+    if (fenceMatch) {
+      const marker = fenceMatch[1];
+      if (!fence) {
+        fence = marker;
+      } else if (marker[0] === fence[0] && marker.length >= fence.length && line.trim() === marker) {
+        fence = null;
+      }
+      output.push(line);
+      return;
+    }
+
+    const importMatch = fence ? null : line.match(IMPORT_LINE);
+    if (!importMatch) {
+      output.push(line);
+      return;
+    }
+
+    const where = `${filePath}:${index + 1}`;
+    const target = path.resolve(baseDir, importMatch[2]);
+    if (!fs.existsSync(target) || !fs.statSync(target).isFile()) {
+      throw new Error(`Cannot import "${importMatch[2]}" (${where}): file not found at ${target}`);
+    }
+    if (chain.includes(target)) {
+      const loop = [...chain.slice(chain.indexOf(target)), target]
+        .map(file => path.basename(file))
+        .join(' → ');
+      throw new Error(`Cannot import "${importMatch[2]}" (${where}): the files import each other (${loop})`);
+    }
+    if (chain.length > MAX_DEPTH) {
+      throw new Error(`Cannot import "${importMatch[2]}" (${where}): imports are nested more than ${MAX_DEPTH} deep`);
+    }
+
+    files.add(target);
+    const text = fs.readFileSync(target, 'utf8').replace(/^/, '');
+    const extension = path.extname(target).toLowerCase();
+
+    if (MARKDOWN_EXTENSIONS.has(extension)) {
+      const body = parseFrontMatter(text).content;
+      output.push(expand(body, target, [...chain, target], files).replace(/(\r?\n)+$/, ''));
+    } else {
+      const code = text.replace(/(\r?\n)+$/, '');
+      const marker = fenceFor(code);
+      output.push(`${marker}${extension.slice(1)}`, code, marker);
+    }
+  });
+
+  return output.join('\n');
+}
+
+/**
+ * Replaces every `@import "path"` line of a Markdown document with the file
+ * it names.
+ * @param {string} markdown Content of the document
+ * @param {string} filePath Path of the document; imports are relative to it
+ * @returns {{ content: string, files: string[] }} The expanded Markdown and
+ *   the absolute path of every file that was imported, directly or not
+ */
+function expandIncludes(markdown = '', filePath = '') {
+  const absolutePath = path.resolve(filePath || 'document.md');
+  const files = new Set();
+  const content = expand(markdown, absolutePath, [absolutePath], files);
+  return { content, files: Array.from(files) };
+}
+
+module.exports = {
+  expandIncludes
+};

package/src/core/index.js

@@ -1,15 +1,55 @@
+/*! 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');
+
+const FORMATS = ['pdf', 'html', 'docx', 'epub'];
 
 /**
- * Main function to convert Markdown file to PDF
+ * Where the page the browser prints is written: beside the Markdown file, so
+ * that its relative pictures and links resolve as they do in the source, also
+ * when the PDF goes to another folder. Falls back to the PDF's folder when the
+ * source's folder cannot be written to.
+ * @param {string} absInputPath
+ * @param {string} absOutputPath
+ * @returns {string}
+ */
+function temporaryHtmlPath(absInputPath, absOutputPath) {
+  const name = `_temp_${Date.now()}_${Math.random().toString(36).substring(7)}.html`;
+  const sourceDir = path.dirname(absInputPath);
+  try {
+    fs.accessSync(sourceDir, fs.constants.W_OK);
+    return path.join(sourceDir, name);
+  } catch (_) {
+    return path.join(path.dirname(absOutputPath), name);
+  }
+}
+
+/**
+ * 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`)
  * @param {string} inputPath Path to source .md file
- * @param {string} [outputPath] Path to target .pdf file
+ * @param {string} [outputPath] Path to the target file
  * @param {Object} [options] Conversion options
- * @returns {Promise<{ htmlPath: string, pdfPath: string }>}
+ * @returns {Promise<{ outputPath: string, htmlPath: string, pdfPath: string, includedFiles: string[] }>}
+ *   `outputPath` is the file that was asked for, whatever its format
  */
 async function convertMarkdownToPdf(inputPath, outputPath, options = {}) {
   const absInputPath = resolvePath(inputPath);
@@ -19,6 +59,9 @@ async function convertMarkdownToPdf(inputPath, outputPath, options = {}) {
   }
 
   const format = options.format ? options.format.toLowerCase() : 'pdf';
+  if (!FORMATS.includes(format)) {
+    throw new Error(`Unknown output format "${options.format}". Use one of: ${FORMATS.join(', ')}`);
+  }
 
   // Derive output path if omitted
   let absOutputPath;
@@ -29,8 +72,24 @@ async function convertMarkdownToPdf(inputPath, outputPath, options = {}) {
     absOutputPath = path.join(parsed.dir, `${parsed.name}.${format}`);
   }
 
-  // Read Markdown
-  const markdownContent = fs.readFileSync(absInputPath, 'utf8');
+  // Read Markdown, pulling in the files it imports with `@import "path"`
+  let markdownContent = fs.readFileSync(absInputPath, 'utf8');
+  let includedFiles = [];
+  if (options.include !== false) {
+    ({ content: markdownContent, files: includedFiles } = expandIncludes(markdownContent, absInputPath));
+  }
+
+  // Word and EPUB are written from the Markdown itself, without a browser
+  if (format === 'docx' || format === 'epub') {
+    const build = format === 'docx' ? markdownToDocx : markdownToEpub;
+    fs.writeFileSync(absOutputPath, build(markdownContent, { ...options, baseDir: path.dirname(absInputPath) }));
+    return {
+      outputPath: absOutputPath,
+      htmlPath: null,
+      pdfPath: null,
+      includedFiles
+    };
+  }
 
   // Parse to HTML
   const htmlContent = parseMarkdownToHtml(markdownContent, options);
@@ -38,20 +97,22 @@ async function convertMarkdownToPdf(inputPath, outputPath, options = {}) {
   if (format === 'html') {
     fs.writeFileSync(absOutputPath, htmlContent, 'utf8');
     return {
+      outputPath: absOutputPath,
       htmlPath: absOutputPath,
-      pdfPath: null
+      pdfPath: null,
+      includedFiles
     };
   }
 
   // Temporary HTML path
-  const tempHtmlPath = path.join(path.parse(absOutputPath).dir, `_temp_${Date.now()}_${Math.random().toString(36).substring(7)}.html`);
+  const tempHtmlPath = temporaryHtmlPath(absInputPath, absOutputPath);
 
   try {
     // 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) {
@@ -61,8 +122,10 @@ async function convertMarkdownToPdf(inputPath, outputPath, options = {}) {
     }
 
     return {
+      outputPath: absOutputPath,
       htmlPath: tempHtmlPath,
-      pdfPath: absOutputPath
+      pdfPath: absOutputPath,
+      includedFiles
     };
   } catch (error) {
     // Clean up on failure
@@ -75,6 +138,11 @@ async function convertMarkdownToPdf(inputPath, outputPath, options = {}) {
 
 module.exports = {
   convertMarkdownToPdf,
+  expandIncludes,
+  markdownToDocx,
+  markdownToEpub,
   parseMarkdownToHtml,
-  renderHtmlToPdf
+  pdfOutline,
+  renderHtmlToPdf,
+  temporaryHtmlPath
 };