@kobekeye/mdf 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,82 @@
+# mdf
+
+Convert Markdown to beautiful PDFs — free, open-source, and zero-config.
+
+## Features
+
+- **Syntax highlighting** — fenced code blocks with language detection (via highlight.js)
+- **Math formulas** — inline and block LaTeX via KaTeX (`$...$` and `$$...$$`)
+- **Table of contents** — insert `[TOC]` anywhere in your document
+- **Callout blocks** — `:::info`, `:::warning`, `:::danger`, `:::success`
+- **Task lists** — `- [ ]` and `- [x]`
+- **Tables, images, blockquotes**
+- **Manual page breaks** — insert `==page==` on its own line
+- **CJK support** — uses Inter + Noto Sans TC via Google Fonts (requires internet on first run)
+
+## Installation
+
+```bash
+npm install -g mdf
+```
+
+Or run without installing:
+
+```bash
+npx mdf input.md
+```
+
+## Usage
+
+```bash
+mdf input.md              # outputs input.pdf
+mdf input.md output.pdf   # custom output name
+```
+
+## Syntax Guide
+
+### Table of Contents
+
+```markdown
+[TOC]
+```
+
+### Math
+
+```markdown
+Inline: $E = mc^2$
+
+Block:
+$$
+\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
+$$
+```
+
+### Callout Blocks
+
+```markdown
+:::info Title
+This is an info callout.
+:::
+
+:::warning
+Watch out!
+:::
+
+:::danger Critical
+This is dangerous.
+:::
+
+:::success
+Operation completed.
+:::
+```
+
+### Manual Page Break
+
+```markdown
+==page==
+```
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const puppeteer = require('puppeteer');
+const { renderToHtml } = require('./renderer');
+
+// parse command line arguments
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+    console.log(`
+usage: node index.js <input.md> [output.pdf]
+
+  input.md    required, the Markdown file to convert
+  output.pdf  optional, the output PDF file name
+              (if omitted, it will automatically use the same name, e.g. input.pdf)
+
+examples:
+  node index.js README.md
+  node index.js doc.md custom-name.pdf
+    `);
+    process.exit(0);
+}
+
+const inputFile = args[0];
+const outputFile = args[1] || inputFile.replace(/\.md$/i, '.pdf');
+
+// check if input file exists
+if (!fs.existsSync(inputFile)) {
+    console.error(`\x1b[31mError: file not found: ${inputFile}\x1b[0m`);
+    process.exit(1);
+}
+
+async function convertToPdf() {
+    console.log(`converting: ${inputFile} → ${outputFile}`);
+
+    const fullHtml = renderToHtml(inputFile);
+
+    // write HTML to temp file (in the same directory as Markdown), let Puppeteer parse relative path of images correctly
+    const inputDir = path.dirname(path.resolve(inputFile));
+    const tempHtmlPath = path.join(inputDir, `.mdf-temp-${Date.now()}.html`);
+    fs.writeFileSync(tempHtmlPath, fullHtml, 'utf-8');
+
+    try {
+        const browser = await puppeteer.launch();
+        const page = await browser.newPage();
+
+        // use file:// URL to load, let relative path of images parse correctly
+        await page.goto(`file://${tempHtmlPath}`, { waitUntil: 'networkidle0' });
+        // wait for all fonts (including Google Fonts) to load completely, avoid CJK characters use synthetic bold
+        await page.evaluate(() => document.fonts.ready);
+
+        await page.pdf({
+            path: outputFile,
+            format: 'A4',
+            printBackground: true,
+            margin: { top: '20mm', bottom: '20mm', left: '20mm', right: '20mm' },
+
+            displayHeaderFooter: true,
+            headerTemplate: '<span></span>',  // do not display header
+            footerTemplate: `
+            <div style="width: 100%; text-align: center; font-size: 14px; color: #888; font-family: 'Times New Roman', Times, serif; margin-bottom: 5mm;">
+                <span class="pageNumber"></span>
+            </div>`,
+        });
+
+        await browser.close();
+        console.log(`\x1b[32mDone! Output to: ${path.resolve(outputFile)}\x1b[0m`);
+    } finally {
+        // clean up temp HTML file
+        try { fs.unlinkSync(tempHtmlPath); } catch (_) { }
+    }
+}
+
+convertToPdf().catch((err) => {
+    console.error(`\x1b[31mError: ${err.message}\x1b[0m`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@kobekeye/mdf",
+  "version": "1.0.0",
+  "description": "Convert Markdown to beautiful PDFs — free, open-source, and zero-config.",
+  "main": "index.js",
+  "bin": {
+    "mdf": "./index.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "markdown",
+    "pdf",
+    "converter",
+    "cli",
+    "katex",
+    "syntax-highlighting"
+  ],
+  "author": "kobekeye",
+  "license": "MIT",
+  "type": "commonjs",
+  "dependencies": {
+    "highlight.js": "^11.11.1",
+    "katex": "^0.16.33",
+    "markdown-it": "^14.1.1",
+    "markdown-it-anchor": "^9.2.0",
+    "markdown-it-container": "^4.0.0",
+    "markdown-it-task-lists": "^2.1.1",
+    "markdown-it-texmath": "^1.0.0",
+    "puppeteer": "^24.37.5"
+  }
+}

package/renderer.js

@@ -0,0 +1,212 @@
+const fs = require('fs');
+const path = require('path');
+const MarkdownIt = require('markdown-it');
+const texmath = require('markdown-it-texmath');
+const katex = require('katex');
+const hljs = require('highlight.js');
+const anchor = require('markdown-it-anchor');
+const taskLists = require('markdown-it-task-lists');
+const container = require('markdown-it-container');
+const md = new MarkdownIt({
+    html: true,
+    highlight: function (str, lang) {
+        if (lang && hljs.getLanguage(lang)) {
+            try {
+                return '<pre class="hljs"><code>' +
+                    hljs.highlight(str, { language: lang, ignoreIllegals: true }).value +
+                    '</code></pre>';
+            } catch (_) { }
+        }
+        return '<pre class="hljs"><code>' + md.utils.escapeHtml(str) + '</code></pre>';
+    }
+});
+md.use(texmath, {
+    engine: katex,
+    delimiters: 'dollars',
+});
+md.use(anchor, {
+    permalink: false,
+    slugify: (s) => encodeURIComponent(String(s).trim().toLowerCase().replace(/\s+/g, '-')),
+});
+md.use(taskLists, { enabled: true });
+// --- Callout container blocks: :::info, :::warning, :::danger, :::success ---
+// Color aliases: :::blue = :::info, :::orange = :::warning, etc.
+const CALLOUT_TYPES = [
+    { names: ['info', 'blue'], cssClass: 'info' },
+    { names: ['warning', 'orange'], cssClass: 'warning' },
+    { names: ['danger', 'red'], cssClass: 'danger' },
+    { names: ['success', 'green'], cssClass: 'success' },
+];
+for (const { names, cssClass } of CALLOUT_TYPES) {
+    for (const name of names) {
+        md.use(container, name, {
+            render(tokens, idx) {
+                const token = tokens[idx];
+                if (token.nesting === 1) {
+                    // opening tag – extract optional title after :::type
+                    const titleMatch = token.info.trim().match(new RegExp(`^${name}\\s+(.*)$`));
+                    const title = titleMatch ? titleMatch[1].trim() : '';
+                    const titleHtml = title
+                        ? `<p class="callout-title">${md.utils.escapeHtml(title)}</p>\n`
+                        : '';
+                    return `<div class="callout callout-${cssClass}">\n${titleHtml}`;
+                }
+                return '</div>\n';
+            },
+        });
+    }
+}
+// --- Spoiler (collapsible) container: :::spoiler ---
+md.use(container, 'spoiler', {
+    render(tokens, idx) {
+        const token = tokens[idx];
+        if (token.nesting === 1) {
+            const titleMatch = token.info.trim().match(/^spoiler\s+(.*)$/);
+            const summary = titleMatch ? titleMatch[1].trim() : 'Spoiler';
+            return `<details class="callout-spoiler">\n<summary>${md.utils.escapeHtml(summary)}</summary>\n`;
+        }
+        return '</details>\n';
+    },
+});
+// Unique HTML comment used as TOC marker (survives markdown-it rendering)
+const TOC_MARKER = '<!--TOC_PLACEHOLDER-->';
+// Regex to match [TOC] on its own line in raw Markdown
+const TOC_MD_REGEX = /^\[TOC\]$/gmi;
+/**
+ * Generate a table of contents HTML from rendered HTML headings
+ * @param {string} html - rendered HTML string
+ * @returns {string} TOC HTML string
+ */
+function generateTOC(html) {
+    const headingRegex = /<h([1-6])\s+id="([^"]*)"[^>]*>(.*?)<\/h[1-6]>/gi;
+    const headings = [];
+    let match;
+    while ((match = headingRegex.exec(html)) !== null) {
+        headings.push({
+            level: parseInt(match[1]),
+            id: match[2],
+            text: match[3].replace(/<[^>]+>/g, ''), // strip inner HTML tags
+        });
+    }
+    if (headings.length === 0) return '';
+    // find the minimum heading level to use as base
+    const minLevel = Math.min(...headings.map(h => h.level));
+    let tocHtml = '<nav class="toc">\n<p class="toc-title">Contents</p>\n<ul>\n';
+    let currentLevel = minLevel;
+    let isFirst = true;
+    for (const heading of headings) {
+        const level = heading.level;
+        if (level > currentLevel) {
+            // go deeper: open nested <ul>
+            for (let i = currentLevel; i < level; i++) {
+                tocHtml += '<ul>\n';
+            }
+        } else if (level < currentLevel) {
+            // go up: close nested <ul>
+            for (let i = currentLevel; i > level; i--) {
+                tocHtml += '</ul>\n</li>\n';
+            }
+        } else if (!isFirst) {
+            // same level, close previous <li>
+            tocHtml += '</li>\n';
+        }
+        tocHtml += `<li><a href="#${heading.id}">${heading.text}</a>\n`;
+        currentLevel = level;
+        isFirst = false;
+    }
+    // close remaining open tags
+    for (let i = currentLevel; i >= minLevel; i--) {
+        tocHtml += '</li>\n</ul>\n';
+    }
+    tocHtml += '</nav>';
+    return tocHtml;
+}
+/**
+ * Replace [TOC] in raw Markdown with a unique marker before rendering
+ * @param {string} markdown - raw Markdown string
+ * @returns {string} Markdown with [TOC] replaced by marker
+ */
+function preprocessTOC(markdown) {
+    return markdown.replace(TOC_MD_REGEX, TOC_MARKER);
+}
+/**
+ * Replace TOC marker in rendered HTML with the actual generated TOC
+ * @param {string} html - rendered HTML string
+ * @returns {string} HTML with TOC inserted
+ */
+function processTOC(html) {
+    if (!html.includes(TOC_MARKER)) return html;
+    const toc = generateTOC(html);
+    return html.replace(TOC_MARKER, toc);
+}
+// CSS file paths
+const themePath = path.join(__dirname, 'themes', 'default.css');
+const hljsCssPath = path.join(__dirname, 'node_modules', 'highlight.js', 'styles', 'github-dark.css');
+const texmathCssPath = path.join(__dirname, 'node_modules', 'markdown-it-texmath', 'css', 'texmath.css');
+// KaTeX CSS is referenced as a local file:// URL so its bundled fonts resolve correctly
+const katexCssUrl = `file://${path.join(__dirname, 'node_modules', 'katex', 'dist', 'katex.min.css')}`;
+// CSS cache: read once, avoid I/O on every render
+let cachedThemeCSS = null;
+let cachedHljsCSS = null;
+let cachedTexmathCSS = null;
+function loadCSS() {
+    if (!cachedThemeCSS) {
+        cachedThemeCSS = fs.readFileSync(themePath, 'utf-8');
+        cachedHljsCSS = fs.readFileSync(hljsCssPath, 'utf-8');
+        cachedTexmathCSS = fs.readFileSync(texmathCssPath, 'utf-8');
+    }
+    return { themeCSS: cachedThemeCSS, hljsCSS: cachedHljsCSS, texmathCSS: cachedTexmathCSS };
+}
+/**
+ * render only Markdown body HTML (without <head>, CSS, etc.) for SSE real-time update, avoid full page reload
+ * @param {string} markdownFilePath - Markdown file path
+ * @returns {string} rendered HTML body content
+ */
+function renderBodyHtml(markdownFilePath) {
+    let content = fs.readFileSync(markdownFilePath, 'utf-8');
+    content = content.replace(/^==page==$/gm, '\n<div class="page-break"></div>\n');
+    content = preprocessTOC(content);
+    let html = md.render(content);
+    html = processTOC(html);
+    return html;
+}
+/**
+ * render Markdown file to complete HTML string (including CSS)
+ * @param {string} markdownFilePath - Markdown file path
+ * @param {object} [options] - options
+ * @param {string} [options.extraHeadHtml] - extra HTML to inject into <head>
+ * @param {string} [options.extraBodyHtml] - extra HTML to inject at the end of <body>
+ * @param {string} [options.contentWrapperId] - if provided, wrap content in a div with this ID (for SSE real-time update)
+ * @returns {string} complete HTML string
+ */
+function renderToHtml(markdownFilePath, options = {}) {
+    let markdownContent = fs.readFileSync(markdownFilePath, 'utf-8');
+    markdownContent = markdownContent.replace(/^==page==$/gm, '\n<div class="page-break"></div>\n');
+    markdownContent = preprocessTOC(markdownContent);
+    const { themeCSS, hljsCSS, texmathCSS } = loadCSS();
+    let bodyHtml = md.render(markdownContent);
+    bodyHtml = processTOC(bodyHtml);
+    // if contentWrapperId is provided, wrap content in a div for SSE real-time update
+    if (options.contentWrapperId) {
+        bodyHtml = `<div id="${options.contentWrapperId}">${bodyHtml}</div>`;
+    }
+    const extraHead = options.extraHeadHtml || '';
+    const extraBody = options.extraBodyHtml || '';
+    return `<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <link rel="stylesheet" href="${katexCssUrl}">
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700&family=Noto+Sans+TC:wght@400;700&display=swap" rel="stylesheet">
+    <style>${texmathCSS} ${hljsCSS} ${themeCSS}</style>
+    ${extraHead}
+</head>
+<body>
+    ${bodyHtml}
+    ${extraBody}
+</body>
+</html>`;
+}
+module.exports = { renderToHtml, renderBodyHtml };

package/themes/default.css

@@ -0,0 +1,370 @@
+/* global */
+*,
+*::before,
+*::after {
+    box-sizing: border-box;
+}
+
+body {
+    font-family: 'inter', 'noto sans tc', sans-serif;
+    font-size: 15px;
+    line-height: 1.75;
+    color: #1a1a2e;
+    background: #ffffff;
+    max-width: 780px;
+    margin: 0 auto;
+    padding: 0;
+    -webkit-font-smoothing: antialiased;
+}
+
+/* headings */
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+    font-weight: 700;
+    line-height: 1.3;
+    margin-top: 2em;
+    margin-bottom: 0.6em;
+    color: #0d0d1a;
+}
+
+h1 {
+    font-size: 2em;
+    padding-bottom: 0.3em;
+    border-bottom: 2px solid #e8eaf0;
+    margin-top: 0;
+}
+
+/* ensure the first element on every page has no top margin */
+body> :first-child {
+    margin-top: 0;
+}
+
+.page-break+* {
+    margin-top: 0;
+}
+
+h2 {
+    font-size: 1.4em;
+    padding-bottom: 0.2em;
+    border-bottom: 1px solid #e8eaf0;
+}
+
+h3 {
+    font-size: 1.15em;
+}
+
+h4 {
+    font-size: 1em;
+    color: #444;
+}
+
+/* paragraphs and texts */
+p {
+    margin: 0 0 1em;
+}
+
+a {
+    color: #3b82f6;
+    text-decoration: none;
+    border-bottom: 1px solid rgba(59, 130, 246, 0.3);
+}
+
+strong {
+    font-weight: 700;
+    color: #0d0d1a;
+}
+
+em {
+    font-style: italic;
+    color: #333;
+}
+
+/* code */
+code {
+    font-family: 'jetbrains mono', 'menlo', monospace;
+    font-size: 0.85em;
+    background: #ebebeb;
+    color: #1a1a1a;
+    padding: 0.15em 0.4em;
+    border-radius: 4px;
+}
+
+/* code blocks */
+pre {
+    font-family: 'jetbrains mono', 'menlo', monospace;
+    font-size: 0.82em;
+    line-height: 1.65;
+    background: #1e1e2e;
+    color: #cdd6f4;
+    padding: 20px 24px;
+    border-radius: 4px;
+    overflow-x: auto;
+    margin: 1.2em 0;
+    border: 1px solid #2a2a3e;
+}
+
+pre code {
+    background: none;
+    color: inherit;
+    padding: 0;
+    font-size: inherit;
+    border-radius: 0;
+}
+
+/* blockquotes */
+blockquote {
+    margin: 1.2em 0;
+    padding: 12px 20px;
+    border-left: 4px solid #3b82f6;
+    background: #f0f6ff;
+    border-radius: 0 4px 4px 0;
+    color: #334155;
+}
+
+blockquote p {
+    margin: 0;
+}
+
+/* horizontal rules */
+hr {
+    border: none;
+    border-top: 2px solid #e8eaf0;
+    margin: 2em 0;
+}
+
+/* lists */
+ul,
+ol {
+    padding-left: 1.6em;
+    margin: 0.5em 0 1em;
+}
+
+li {
+    margin: 0.3em 0;
+}
+
+/* task lists */
+ul.contains-task-list {
+    list-style-type: none;
+    padding-left: 0.2em;
+}
+
+li.task-list-item {
+    list-style: none;
+}
+
+li.task-list-item input[type="checkbox"] {
+    margin-right: 6px;
+    cursor: pointer;
+}
+
+/* tables */
+table {
+    width: 100%;
+    table-layout: fixed;
+    border-collapse: collapse;
+    margin: 1.2em 0;
+    font-size: 0.92em;
+}
+
+thead tr {
+    background: #f5f6ff;
+    border-bottom: 2px solid #d4d8f0;
+}
+
+th {
+    font-weight: 600;
+    text-align: left;
+    padding: 10px 14px;
+    color: #0d0d1a;
+    border: 1px solid #d4d8f0;
+}
+
+td {
+    padding: 9px 14px;
+    border: 1px solid #e8eaf0;
+    color: #334155;
+}
+
+tr:nth-child(even) td {
+    background: #fafafe;
+}
+
+/* images */
+img {
+    max-width: 100%;
+    border-radius: 6px;
+    display: block;
+    margin: 1em auto;
+}
+
+/* fundamental automatic page breaks */
+h1,
+h2,
+h3,
+h4 {
+    break-after: avoid;
+}
+
+pre,
+blockquote,
+img,
+table,
+figure {
+    break-inside: avoid;
+}
+
+/* manual page breaks */
+.page-break {
+    break-after: page;
+}
+
+/* table of contents */
+.toc {
+    background: #f8f9fc;
+    border: 1px solid #e2e5f0;
+    border-radius: 6px;
+    padding: 20px 28px;
+    margin: 1.5em 0 2em;
+}
+
+.toc-title {
+    font-weight: 700;
+    font-size: 1.15em;
+    color: #0d0d1a;
+    margin: 0 0 0.6em;
+    padding-bottom: 0.4em;
+    border-bottom: 1px solid #e2e5f0;
+}
+
+.toc ul {
+    list-style: none;
+    padding-left: 0;
+    margin: 0;
+}
+
+.toc ul ul {
+    padding-left: 1.4em;
+}
+
+.toc li {
+    margin: 0.25em 0;
+}
+
+.toc a {
+    color: #3b5998;
+    border-bottom: none;
+    text-decoration: none;
+    font-size: 0.95em;
+}
+
+.toc a:hover {
+    color: #3b82f6;
+    text-decoration: underline;
+}
+
+/* ===== Callout container blocks ===== */
+.callout {
+    margin: 1.2em 0;
+    padding: 14px 20px;
+    border-left: 4px solid;
+    border-radius: 0 6px 6px 0;
+    font-size: 0.95em;
+    line-height: 1.7;
+    break-inside: avoid;
+}
+
+.callout p {
+    margin: 0 0 0.5em;
+}
+
+.callout p:last-child {
+    margin-bottom: 0;
+}
+
+.callout strong,
+.callout-spoiler strong {
+    color: inherit;
+}
+
+.callout-title {
+    font-weight: 700;
+    margin: 0 0 0.4em !important;
+    font-size: 1em;
+}
+
+/* info – blue */
+.callout-info {
+    border-left-color: #3b82f6;
+    background: #eff6ff;
+    color: #1e3a5f;
+}
+
+.callout-info .callout-title {
+    color: #2563eb;
+}
+
+/* warning – amber */
+.callout-warning {
+    border-left-color: #f59e0b;
+    background: #fffbeb;
+    color: #78350f;
+}
+
+.callout-warning .callout-title {
+    color: #d97706;
+}
+
+/* danger – red */
+.callout-danger {
+    border-left-color: #ef4444;
+    background: #fef2f2;
+    color: #7f1d1d;
+}
+
+.callout-danger .callout-title {
+    color: #dc2626;
+}
+
+/* success – green */
+.callout-success {
+    border-left-color: #22c55e;
+    background: #f0fdf4;
+    color: #14532d;
+}
+
+.callout-success .callout-title {
+    color: #16a34a;
+}
+
+/* spoiler – collapsible */
+.callout-spoiler {
+    margin: 1.2em 0;
+    padding: 14px 20px;
+    border-left: 4px solid #94a3b8;
+    background: #f8fafc;
+    border-radius: 0 6px 6px 0;
+    break-inside: avoid;
+}
+
+.callout-spoiler summary {
+    font-weight: 700;
+    cursor: pointer;
+    color: #475569;
+    font-size: 0.95em;
+    user-select: none;
+}
+
+.callout-spoiler summary:hover {
+    color: #334155;
+}
+
+.callout-spoiler[open] summary {
+    margin-bottom: 0.6em;
+    padding-bottom: 0.4em;
+    border-bottom: 1px solid #e2e8f0;
+}