@dr-ishaan/rehype-perfect-code-blocks 2.0.0 → 2.2.0

package/src/types.ts

@@ -122,6 +122,21 @@ export interface PerfectCodeOptions {
     transformerOrder?: 'before' | 'after';
     /** Override the highlighter factory (e.g. for custom TextMate grammars). */
     getHighlighter?: (opts: { themes: string[]; langs: string[] }) => Promise<unknown>;
+    /**
+     * v2.1.0: Lazy initialization — don't load Shiki until the first code block
+     * is encountered. On pages with no code blocks, Shiki (and its WASM engine)
+     * is never loaded, saving ~1MB of bundle.
+     *
+     * Default: false (Shiki initializes eagerly, same as v1.x/v2.0)
+     */
+    lazy?: boolean;
+    /**
+     * v2.1.0: Languages to preload when lazy is true. Only loaded if the
+     * document contains at least one code block.
+     *
+     * Default: ['typescript', 'bash', 'javascript', 'json', 'html', 'css']
+     */
+    preloadLangs?: string[];
     [key: string]: unknown;
   };
   /**
@@ -491,6 +506,109 @@ export interface PerfectCodeOptions {
    */
   scope?: string;
 
+  /* ---------- v2.1.0: Math/LaTeX rendering ---------- */
+
+  /**
+   * Math/LaTeX rendering via KaTeX. When enabled, the plugin intercepts:
+   *   - Inline math: `$...$` in text (when `math.inline` is true)
+   *   - Block math: `$$...$$` blocks (when `math.block` is true)
+   *   - Fenced code blocks with language `math`, `latex`, or `tex`
+   *
+   * KaTeX renders at build time (server-side) — no client-side JS needed.
+   * The KaTeX CSS + fonts must be loaded on the client (the plugin injects
+   * a `<link>` to KaTeX CSS if `math.injectCss` is true).
+   *
+   * `katex` must be installed: `npm install katex`
+   *
+   * Default: `undefined` (no math rendering; `$...$` renders as literal text)
+   */
+  math?: {
+    /** Math engine. 'katex' renders via KaTeX (must be installed). Default: 'none' */
+    engine?: 'katex' | 'none';
+    /** Render inline `$...$` math. Default: true */
+    inline?: boolean;
+    /** Render block `$$...$$` and ```math blocks. Default: true */
+    block?: boolean;
+    /** Inject KaTeX CSS alongside plugin CSS. Default: true */
+    injectCss?: boolean;
+    /** Don't crash on invalid LaTeX — render the source as-is. Default: true */
+    throwOnError?: boolean;
+    /** Allow non-standard LaTeX commands. Default: false */
+    strict?: boolean | 'ignore' | 'error' | 'warn';
+  };
+
+  /* ---------- v2.1.0: Development warnings ---------- */
+
+  /**
+   * Emit warnings to the logger during build/dev for common misconfigurations:
+   *   - Unknown language not loaded in Shiki
+   *   - Invalid meta syntax (e.g., `{1,a-5}` instead of `{1,3-5}`)
+   *   - Conflicting options (e.g., `wrap` + `collapseAfter` both enabled)
+   *   - Code block inside raw HTML detected but rehype-raw not installed
+   *
+   * Default: true in development (when `NODE_ENV !== 'production'`), false in production.
+   */
+  devWarnings?: boolean;
+
+  /* ---------- v2.2.0: Diff & Comparison ---------- */
+
+  /**
+   * Side-by-side diff view. When enabled, adjacent `+`/`-` diff line pairs
+   * are rendered in a two-column layout (Before | After) with synchronized
+   * scrolling, instead of the default unified diff view.
+   *
+   * On mobile (viewport < 768px), the columns stack vertically.
+   *
+   * Default: `'unified'` (backward-compatible with v1.x/v2.0/v2.1)
+   */
+  diffMode?: 'unified' | 'split';
+
+  /* ---------- v2.2.0: Annotations ---------- */
+
+  /**
+   * Line annotations — margin notes attached to specific code lines.
+   *
+   * Use `// [!ann: "explanation"]` notation inside code to annotate a line.
+   * The annotation appears on the right side of the code block, connected
+   * to the annotated line with a subtle connector line. On mobile,
+   * annotations appear inline below the annotated line.
+   *
+   * Example:
+   * ```ts
+   * const attention = Q.dot(K.T) / Math.sqrt(d)  // [!ann: "Scaled dot-product"]
+   * const weights = softmax(attention)            // [!ann: "Normalized weights"]
+   * ```
+   *
+   * Default: `false` (opt-in)
+   */
+  annotations?: boolean;
+
+  /* ---------- v2.2.0: Attribution ---------- */
+
+  /**
+   * Code attribution — structured metadata for code blocks.
+   *
+   * When enabled, the plugin parses `author`, `year`, and `source` attributes
+   * from the fence meta string and renders them as a footer below the code block:
+   *
+   * ````markdown
+   * ```ts title="perceptron.ts" author="Rosenblatt" year="1958" source="Principles of Neurodynamics"
+   * const output = stepFunction(inputs.dot(weights))
+   * ```
+   * ````
+   *
+   * Renders:
+   * ```
+   * ┌─ perceptron.ts ──────────────────┐
+   * │ const output = stepFunction(...)  │
+   * └───────────────────────────────────┘
+   *   Rosenblatt (1958). Principles of Neurodynamics.
+   * ```
+   *
+   * Default: `false` (opt-in; when disabled, author/year/source meta is silently ignored)
+   */
+  attribution?: boolean;
+
   /* ---------- Inline code (legacy cosmetic option) ---------- */
   /** Also style inline `code` cosmetically (no tokenization). Default: false */
   inline?: boolean;
@@ -515,6 +633,10 @@ export interface ParsedMeta {
   wordHighlights: { text: string; range?: [number, number]; id?: string }[];
   lineNumbersStart: number | null;         // from ln{N} or showLineNumbers{N}
   collapseRanges: { from: number; to: number }[];  // from collapse="5-12,20-30"
+  // v2.2.0: Attribution metadata
+  author: string | null;                   // from author="..."
+  year: string | null;                     // from year="..."
+  source: string | null;                   // from source="..."
   flags: {
     wrap: boolean | null;
     lineNumbers: boolean | null;