md-pdf-studio 2.0.0 → 2.2.0

package/README.md

@@ -27,7 +27,9 @@
 - 🚀 **CLI & Batch Conversion**: Convert single files or batch process directories with wildcard patterns.
 - 🎨 **Custom CSS Injection**: Inject custom branding CSS stylesheets (`-c, --css custom.css`).
 - 📊 **Mermaid Diagrams**: Sequence diagrams (with auto note wrapping), flowcharts, class diagrams, and gantt charts.
+- 🌈 **Syntax Highlighting**: Fenced code blocks that name a language (` ```js `, ` ```python `, ` ```diff `, …) are coloured at build time with highlight.js — no CDN, so it also works offline and in static HTML export. Colours follow the theme's code block background. Works in the CLI and in the extension preview.
 - 📐 **LaTeX Math Support**: Mathematical equations rendered with KaTeX.
+- 📝 **Footnotes**: `text[^1]` with `[^1]: the note` anywhere in the file. Notes are numbered in the order they are first referenced, gathered at the end of the document, and linked both ways. Works in the CLI and in the extension preview.
 - 💡 **GitHub Callout Box Alerts**: Support for `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, `> [!IMPORTANT]`, and `> [!CAUTION]`.
 - 💻 **ASCII UI Mockups**: Styled dark-theme boxes for terminal output & ASCII wireframe mockups.
 
@@ -103,6 +105,7 @@ npx md-pdf-studio ./docs/ -o ./dist/
 | `-k, --keep-html` | | Keep temporary HTML file after conversion | `false` |
 | `--no-mermaid` | | Disable Mermaid diagram rendering | `false` |
 | `--no-katex` | | Disable KaTeX math formula rendering | `false` |
+| `--no-highlight` | | Disable syntax highlighting of code blocks | `false` |
 
 ---
 
@@ -122,6 +125,7 @@ theme: github
 font: Inter
 pageSize: A4
 landscape: false
+highlight: true
 ---
 # Document Executive Summary
 ...
@@ -134,15 +138,18 @@ landscape: false
 This project follows standard **Git Flow** branching and automated release publishing:
 
 ### 🔀 Branching Strategy
-- **`main`**: Production-ready branch. Stores stable releases. Merging code into `main` automatically triggers a GitHub Release.
+- **`main`**: Production-ready branch. Stores stable releases. Pushing a version tag `v*` from `main` triggers a release.
 - **`develop`**: Active development branch. Daily commits, feature additions, and refactoring take place here.
 
 ### 🚀 Automated Release Pipeline
-Whenever code is merged from `develop` into `main` (or a version tag `v*` is pushed), GitHub Actions ([`.github/workflows/release.yml`](.github/workflows/release.yml)) automatically:
-1. Runs full unit test suite (`npm test`).
+Whenever a version tag `v*` is pushed, GitHub Actions ([`.github/workflows/release.yml`](.github/workflows/release.yml)) builds from that tag and automatically:
+1. Checks that the tag matches the version in `package.json` and `extension/manifest.json`, then runs the full unit test suite (`npm test`).
 2. Bundles cross-platform extension zip artifacts (`dist/extension-vX.Y.Z.zip`).
 3. Auto-generates release notes from commit history.
 4. Publishes a new official **[GitHub Release](https://github.com/vannt-dev/convert-md-to-pdf/releases)** with downloadable ZIP binaries attached!
+5. Publishes [`md-pdf-studio`](https://www.npmjs.com/package/md-pdf-studio) to npm with provenance, through npm trusted publishing (no token secret). A version already on npm is skipped.
+
+To release an existing tag again (for example after a failed run), run the workflow manually with `tag_name`.
 
 ### 💡 1-Click CLI Release Command
 You can also bump version and trigger a release with a single CLI command:

package/bin/cli.js

@@ -28,6 +28,7 @@ program
   .option('-k, --keep-html', 'Keep temporary HTML file after conversion', false)
   .option('--no-mermaid', 'Disable Mermaid diagram rendering')
   .option('--no-katex', 'Disable KaTeX math formula rendering')
+  .option('--no-highlight', 'Disable syntax highlighting of code blocks')
   .option('-b, --browser <path>', 'Custom Chrome/Edge executable path')
   .action(async (inputArgs, options) => {
     try {
@@ -89,6 +90,7 @@ program
             keepHtml: options.keepHtml,
             mermaid: options.mermaid,
             katex: options.katex,
+            highlight: options.highlight,
             executablePath: options.browser
           });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "md-pdf-studio",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "A powerful CLI tool and Manifest V3 Browser Extension to convert Markdown files, text, or web pages into beautifully styled PDFs with Mermaid diagrams, LaTeX math, TOC, and themes.",
   "main": "src/core/index.js",
   "bin": {
@@ -47,6 +47,7 @@
   },
   "dependencies": {
     "commander": "^15.0.0",
+    "highlight.js": "^11.12.0",
     "marked": "^18.0.14"
   },
   "engines": {

package/src/core/footnotes.js

@@ -0,0 +1,122 @@
+/**
+ * Markdown footnotes: `text[^id]` in the body, `[^id]: note` anywhere on a line of its own.
+ *
+ * Works on the Markdown text, before it is parsed, and needs nothing from Node: the same file
+ * is shipped in the extension as extension/lib/footnotes.js (a test keeps the two identical).
+ */
+(function (scope) {
+  const DEFINITION = /^ {0,3}\[\^([^\]\s]+)\]:[ \t]*(.*)$/;
+  const REFERENCE = /\[\^([^\]\s]+)\]/g;
+  const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+  const CONTINUATION = /^(?: {2,}|\t)\S/;
+
+  /**
+   * Splits the text into lines tagged as code or prose. Footnote syntax inside a fenced
+   * block is an example of the syntax, not a footnote.
+   * @param {string} markdown
+   * @returns {{ text: string, code: boolean }[]}
+   */
+  function tagLines(markdown) {
+    const lines = [];
+    let fence = null;
+    for (const text of markdown.split(/\r?\n/)) {
+      const match = FENCE.exec(text);
+      if (fence) {
+        lines.push({ text, code: true });
+        if (match && match[1][0] === fence[0] && match[1].length >= fence.length) fence = null;
+      } else if (match) {
+        fence = match[1];
+        lines.push({ text, code: true });
+      } else {
+        lines.push({ text, code: false });
+      }
+    }
+    return lines;
+  }
+
+  /**
+   * Applies `replace` to the parts of a line that are not inline code.
+   * @param {string} line
+   * @param {(prose: string) => string} replace
+   * @returns {string}
+   */
+  function outsideInlineCode(line, replace) {
+    return line
+      .split(/(`+[^`]*`+)/)
+      .map((part, index) => (index % 2 === 1 ? part : replace(part)))
+      .join('');
+  }
+
+  /**
+   * Numbers the footnotes of a Markdown document in the order they are first referenced,
+   * replaces each reference with a superscript link, and appends the notes as a list.
+   *
+   * A reference to a note that is never defined is left as the author typed it; a note that
+   * is never referenced is left out, as GitHub does.
+   * @param {string} markdown
+   * @returns {string} Markdown, with HTML for the references and the notes section
+   */
+  function applyFootnotes(markdown = '') {
+    if (!markdown || markdown.indexOf('[^') === -1) return markdown;
+
+    const lines = tagLines(markdown);
+    const definitions = new Map();
+    const body = [];
+
+    for (let index = 0; index < lines.length; index++) {
+      const line = lines[index];
+      const match = line.code ? null : DEFINITION.exec(line.text);
+      if (!match) {
+        body.push(line);
+        continue;
+      }
+      const parts = [match[2].trim()];
+      // Indented lines that follow belong to the note.
+      while (
+        index + 1 < lines.length &&
+        !lines[index + 1].code &&
+        CONTINUATION.test(lines[index + 1].text)
+      ) {
+        index += 1;
+        parts.push(lines[index].text.trim());
+      }
+      // The first definition of an id wins, as with link reference definitions.
+      if (!definitions.has(match[1])) definitions.set(match[1], parts.join(' ').trim());
+    }
+
+    if (definitions.size === 0) return markdown;
+
+    const numbers = new Map();
+    const uses = new Map();
+    const text = body
+      .map((line) => {
+        if (line.code) return line.text;
+        return outsideInlineCode(line.text, (prose) =>
+          prose.replace(REFERENCE, (whole, id) => {
+            if (!definitions.has(id)) return whole;
+            if (!numbers.has(id)) numbers.set(id, numbers.size + 1);
+            const number = numbers.get(id);
+            const use = (uses.get(id) || 0) + 1;
+            uses.set(id, use);
+            const anchor = use === 1 ? `fnref-${number}` : `fnref-${number}-${use}`;
+            return `<sup class="footnote-ref"><a href="#fn-${number}" id="${anchor}">${number}</a></sup>`;
+          })
+        );
+      })
+      .join('\n');
+
+    if (numbers.size === 0) return text;
+
+    const notes = Array.from(numbers.entries()).map(([id, number]) => {
+      const note = definitions.get(id);
+      return `${number}. <span id="fn-${number}"></span>${note} <a href="#fnref-${number}" class="footnote-backref" aria-label="Back to the text">↩</a>`;
+    });
+
+    // The blank lines let Markdown inside the section be parsed as Markdown.
+    return `${text.replace(/\s+$/, '')}\n\n<section class="footnotes">\n\n${notes.join('\n')}\n\n</section>\n`;
+  }
+
+  const api = { applyFootnotes };
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else scope.MdPdfFootnotes = api;
+})(typeof globalThis !== 'undefined' ? globalThis : this);

package/src/core/parser.js

@@ -1,4 +1,5 @@
 const { marked } = require('marked');
+const hljs = require('highlight.js/lib/common');
 const { 
   parseFrontMatter, 
   generateCoverPage, 
@@ -9,13 +10,15 @@ const {
   escapeHtml 
 } = require('./utils');
 const { getHtmlTemplate } = require('./templates');
+const { applyFootnotes } = require('./footnotes');
 
 /**
  * Builds marked custom renderer for diagrams, UI mockups, and headings
  * @param {Map<string, string>} headingsMap 
+ * @param {boolean} highlight Colour fenced code blocks that name a known language
  * @returns {marked.Renderer}
  */
-function buildMarkedRenderer(headingsMap) {
+function buildMarkedRenderer(headingsMap, highlight = true) {
   const renderer = new marked.Renderer();
   const originalCodeRenderer = renderer.code.bind(renderer);
 
@@ -31,6 +34,13 @@ function buildMarkedRenderer(headingsMap) {
       return `<div class="ui-mockup-container"><pre class="ui-mockup"><code>${escapeHtml(text)}</code></pre></div>`;
     }
 
+    // Only fences that name a language are coloured: guessing one gets short snippets wrong.
+    const language = lang.trim().split(/\s+/)[0];
+    if (highlight && language && hljs.getLanguage(language)) {
+      const highlighted = hljs.highlight(text, { language, ignoreIllegals: true }).value;
+      return `<pre><code class="hljs language-${escapeHtml(language)}">${highlighted}</code></pre>\n`;
+    }
+
     return originalCodeRenderer.call(this, token);
   };
 
@@ -86,12 +96,13 @@ function parseMarkdownToHtml(rawMarkdownContent, options = {}) {
     footer: options.footer !== undefined ? options.footer : (frontMatter.footer || true),
     mermaid: options.mermaid !== undefined ? options.mermaid : (frontMatter.mermaid !== false),
     katex: options.katex !== undefined ? options.katex : (frontMatter.katex !== false),
+    highlight: options.highlight !== undefined ? options.highlight : (frontMatter.highlight !== false),
     customCss: options.customCss || '',
     cssFile: options.cssFile || frontMatter.cssFile || frontMatter.css
   };
 
-  // 3. Preprocess Markdown (LaTeX, pagebreaks, alerts)
-  const processedMd = preprocessMarkdown(markdownContent);
+  // 3. Preprocess Markdown (footnotes, LaTeX, pagebreaks, alerts)
+  const processedMd = preprocessMarkdown(applyFootnotes(markdownContent));
 
   // 4. Generate TOC & Cover Page
   let tocHtml = '';
@@ -118,7 +129,7 @@ function parseMarkdownToHtml(rawMarkdownContent, options = {}) {
 
   // 6. Parse Markdown using custom renderer
   marked.setOptions({ gfm: true, breaks: true });
-  const renderer = buildMarkedRenderer(headingsMap);
+  const renderer = buildMarkedRenderer(headingsMap, mergedOptions.highlight);
   marked.use({ renderer });
 
   let bodyHtml = marked.parse(processedMd);

package/src/core/sanitizer.js

@@ -11,7 +11,29 @@ function sanitizeHtml(html) {
   if (!html) return '';
   return html
     .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '')
-    .replace(/\s*on\w+\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, '');
+    .replace(OPENING_TAG, stripEventHandlers);
+}
+
+// An opening tag, with quoted attribute values allowed to contain ">". A quote that is never
+// closed still ends at the next ">", as the tag would in a lenient parser.
+const OPENING_TAG = /<([a-zA-Z][^\s/>]*)((?:"[^"]*"|'[^']*'|[^>])*)>/g;
+// One attribute: its name, then an optional value. Consuming the value keeps it from being
+// read as another attribute.
+const ATTRIBUTE = /[\s/]*([^\s"'<>/=]+)(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+))?/g;
+
+/**
+ * Drops on* attributes from one opening tag. Text between tags is never touched, so code
+ * such as `el.onclick = fn` survives.
+ * @param {string} tag
+ * @param {string} name
+ * @param {string} attributes
+ * @returns {string}
+ */
+function stripEventHandlers(tag, name, attributes) {
+  const kept = attributes.replace(ATTRIBUTE, (attribute, attributeName) =>
+    /^on/i.test(attributeName) ? '' : attribute
+  );
+  return `<${name}${kept}>`;
 }
 
 /**

package/src/core/templates.js

@@ -99,6 +99,12 @@ function getHtmlTemplate({ title, author = '', bodyHtml, options = {} }) {
       page-break-after: always;
     }
 
+    .footnote-ref { font-size: 0.75em; line-height: 0; }
+    .footnote-ref a, .footnote-backref { text-decoration: none; }
+    .footnotes { margin-top: 28px; padding-top: 10px; border-top: 1px solid currentColor; font-size: 0.85em; break-inside: avoid-page; }
+    .footnotes ol { margin: 0; padding-left: 1.6em; }
+    .footnotes li { margin: 3px 0; }
+
     img {
       max-width: 100% !important;
       height: auto !important;

package/src/core/themes/highlight.js

@@ -0,0 +1,38 @@
+/**
+ * Syntax Highlighting Token Colors
+ * Two palettes, picked by the background each theme gives its code blocks.
+ */
+// Inline-code chrome must not repeat on every line of a block.
+const base = `
+  pre code { background: none; padding: 0; border: none; }
+`;
+
+const light = `
+  .hljs-comment, .hljs-quote, .hljs-meta { color: #6e7781; font-style: italic; }
+  .hljs-keyword, .hljs-selector-tag, .hljs-doctag, .hljs-template-tag { color: #cf222e; }
+  .hljs-string, .hljs-regexp, .hljs-char.escape_ { color: #0a3069; }
+  .hljs-number, .hljs-literal, .hljs-attr, .hljs-attribute, .hljs-variable, .hljs-template-variable, .hljs-symbol, .hljs-bullet { color: #0550ae; }
+  .hljs-title, .hljs-section, .hljs-selector-id, .hljs-selector-class { color: #8250df; }
+  .hljs-type, .hljs-built_in, .hljs-params { color: #953800; }
+  .hljs-name, .hljs-tag { color: #116329; }
+  .hljs-addition { color: #116329; background-color: #dafbe1; }
+  .hljs-deletion { color: #82071e; background-color: #ffebe9; }
+  .hljs-emphasis { font-style: italic; }
+  .hljs-strong { font-weight: 700; }
+`;
+
+const dark = `
+  .hljs-comment, .hljs-quote, .hljs-meta { color: #8b949e; font-style: italic; }
+  .hljs-keyword, .hljs-selector-tag, .hljs-doctag, .hljs-template-tag { color: #ff7b72; }
+  .hljs-string, .hljs-regexp, .hljs-char.escape_ { color: #a5d6ff; }
+  .hljs-number, .hljs-literal, .hljs-attr, .hljs-attribute, .hljs-variable, .hljs-template-variable, .hljs-symbol, .hljs-bullet { color: #79c0ff; }
+  .hljs-title, .hljs-section, .hljs-selector-id, .hljs-selector-class { color: #d2a8ff; }
+  .hljs-type, .hljs-built_in, .hljs-params { color: #ffa657; }
+  .hljs-name, .hljs-tag { color: #7ee787; }
+  .hljs-addition { color: #aff5b4; background-color: #033a16; }
+  .hljs-deletion { color: #ffdcd7; background-color: #67060c; }
+  .hljs-emphasis { font-style: italic; }
+  .hljs-strong { font-weight: 700; }
+`;
+
+module.exports = { light: base + light, dark: base + dark };

package/src/core/themes/index.js

@@ -6,6 +6,7 @@ const githubTheme = require('./github');
 const ebookTheme = require('./ebook');
 const cyberpunkTheme = require('./cyberpunk');
 const minimalTheme = require('./minimal');
+const highlightCss = require('./highlight');
 
 const THEMES = {
   modern: modernTheme,
@@ -17,6 +18,9 @@ const THEMES = {
   minimal: minimalTheme
 };
 
+// Themes whose code blocks sit on a dark background; the others use the light palette.
+const DARK_CODE_THEMES = new Set(['modern', 'dark', 'ebook', 'cyberpunk']);
+
 /**
  * Builds font override CSS string
  * @param {string} font 
@@ -40,10 +44,12 @@ function getFontOverrideCss(font) {
  * @returns {string} Consolidated CSS string
  */
 function getThemeStyles(theme, font = '') {
-  const themeCss = THEMES[theme] || THEMES.modern;
+  const themeName = THEMES[theme] ? theme : 'modern';
+  const themeCss = THEMES[themeName];
+  const tokenCss = DARK_CODE_THEMES.has(themeName) ? highlightCss.dark : highlightCss.light;
   const fontOverrideCss = getFontOverrideCss(font);
 
-  return `${coverCss}\n${fontOverrideCss}${themeCss}`;
+  return `${coverCss}\n${fontOverrideCss}${themeCss}${tokenCss}`;
 }
 
 module.exports = {