@behackl/citation-js-extras 0.2.0 → 0.2.1

package/README.md

@@ -74,7 +74,9 @@ const rendered = bib.formatHtml(bib.entries, {
 `myMathRenderer` is an application-supplied function returning **trusted HTML**
 (e.g. MathJax SVG or KaTeX output). No math renderer is bundled. Configure it for
 untrusted TeX as appropriate; the callback output is inserted verbatim, not
-sanitized. Exceptions propagate to the caller. `renderMath` also works with
+sanitized. Treat renderer output as untrusted HTML unless you control both the
+renderer configuration and the TeX: substitute it only after the surrounding
+HTML has been sanitized (see below). Exceptions propagate to the caller. `renderMath` also works with
 `formatEntry`; it has no effect unless `preserveMath` was enabled.
 
 Supported delimiters are `$…$`, `$$…$$`, `\(…\)`, and `\[…\]`.
@@ -100,6 +102,46 @@ Restoration runs after title linking, badges, and URL linkification. Neither
 renderer output nor restored TeX is fed back through these HTML helpers. Disabling
 preservation (the default) retains the previous behavior.
 
+If `renderMath` throws, the error names the entry it came from
+(`entry doe:2024: Undefined control sequence: \\kk`), so a broken formula can be
+traced to a line in the `.bib` file.
+
+### Sanitizing formatted output
+
+Rendered mathematics does **not** survive an HTML sanitizer with default
+settings: KaTeX and MathJax output relies on `class`, `style` and MathML
+elements that `rehype-sanitize` strips, leaving empty boxes. Sanitize the
+citation HTML *first*, then insert the trusted renderer output:
+
+```js
+const math = [];
+const html = bib.formatHtml(entries, {
+  // Stand in for each formula while the HTML is sanitized ...
+  renderMath: (tex, { display }) => {
+    math.push(renderWithKatex(tex, display));
+    return `mathplaceholder${math.length - 1}end`;
+  },
+});
+const safe = sanitize(html);
+// ... then substitute the rendered markup back in.
+const final = safe.replace(/mathplaceholder(\d+)end/g, (_, i) => math[Number(i)]);
+```
+
+Two related gotchas when using `rehype-sanitize`:
+
+- its `defaultSchema` allows `className` only with an explicit value list *per
+  tag*, and that per-tag rule overrides anything added under `'*'`; to keep
+  badge or list classes, merge your class names into the existing entry for
+  that tag
+- pick a placeholder that cannot occur in your bibliography (append characters
+  until it is absent from the source)
+
+This recipe deliberately reinserts renderer output *after* sanitizing, so it is
+only as safe as the renderer: a renderer configured to emit arbitrary markup
+(for instance KaTeX with `trust: true`) can reintroduce `<script>`. Restrict the
+renderer configuration, or sanitize its output separately with a schema that
+keeps the elements and attributes mathematics needs.
+
 ## Development checks
 
 ```sh
@@ -125,6 +167,13 @@ Use Node 24 LTS for these development checks, matching CI and publishing.
 | `cslStyle` | `string?` | CSL style — a registered template name, raw XML, or a file path. Defaults to `'apa'`. |
 | `customFields` | `string[]?` | BibTeX field names to preserve. These appear on each entry under `.custom`. |
 | `preserveMath` | `boolean?` | Preserve math in display-text fields through CSL formatting. Defaults to `false`. |
+| `titleLink` | `string[]?` | Default fields used for the title link, checked in order. Defaults to `['url', 'doi', 'arxiv']`. |
+| `badges` | `BadgeConfig[]?` | Default badge configuration, used by every `formatHtml`/`formatEntry` call. No badges are rendered unless set. |
+| `linkifyUrls` | `boolean?` | Default for URL linkification. Defaults to `true`. |
+
+`titleLink`, `badges` and `linkifyUrls` are usually the same for every call, so
+they can be set once here; a value passed to `formatHtml`/`formatEntry` overrides
+the default for that call.
 
 ### `bib.entries`
 
@@ -174,10 +223,14 @@ bib.formatHtml(entries, {
 
 Entries are formatted in one citeproc pass, so style-dependent state (for example numeric labels in Vancouver) remains correct.
 
+An empty entry list returns an empty string, not an empty wrapper element.
+
 ### `bib.formatEntry(entry, options?)`
 
 Render a single entry as an HTML string (no list wrapper). The title link targets the actual CSL title text, regardless of italics.
 
+Accepts the same title linking, badge and `linkifyUrls` options as `formatHtml` and applies them identically (`list`/`listAttributes` are ignored — there is no wrapper). Bare URLs are linkified unless `linkifyUrls: false` is set, either per call or on the constructor.
+
 For citation styles that depend on multi-entry context (numbered labels, ibid behavior, etc.), prefer `formatHtml(...)`.
 
 Title links are only created for safe URL schemes (`http`, `https`, `mailto`) or normalized DOI/arXiv links.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { BibEntry, BibliographyOptions, FormatOptions } from "./types.js";
-export type { BadgeConfig, BibEntry, BibliographyOptions, FormatOptions, MathRenderer } from "./types.js";
+export type { BadgeConfig, BibEntry, BibliographyOptions, FormatDefaults, FormatOptions, MathRenderer, } from "./types.js";
 export declare class Bibliography {
     /** The CSL template name to use for formatting. */
     readonly templateName: string;
@@ -7,6 +7,8 @@ export declare class Bibliography {
     readonly entries: BibEntry[];
     private readonly customFieldNames;
     private readonly math?;
+    /** Formatting defaults from the constructor; each call may override them. */
+    private readonly formatDefaults;
     constructor(options: BibliographyOptions);
     /**
      * Return entries whose custom fields match **all** given key/value pairs.
@@ -28,9 +30,26 @@ export declare class Bibliography {
     }): BibEntry[];
     /**
      * Format a single entry as an HTML string (no wrapper element).
-     * Applies title linking and badge injection.
+     * Applies title linking, badge injection and URL linkification.
      */
     formatEntry(entry: BibEntry, options?: FormatOptions): string;
+    /**
+     * Decorate, linkify and restore math for one rendered entry. Shared by
+     * `formatEntry` and `formatHtml` so both honour the same options.
+     *
+     * Linkification runs before math restoration: rendered MathML carries an
+     * xmlns URL that must not be turned into a link. Math is restored per entry
+     * so a failing formula can be reported with its citation key.
+     */
+    private buildEntryHtml;
+    /** Per-call options win over the defaults given to the constructor. */
+    private mergeOptions;
+    /**
+     * Restore protected math, naming the entry when a renderer rejects a formula.
+     * Without the citation key, `renderMath` failures are near-impossible to
+     * trace back to a line in the .bib file.
+     */
+    private restoreMath;
     /**
      * Format a list of entries as a complete HTML bibliography.
      */

package/dist/index.js

@@ -11,9 +11,16 @@ export class Bibliography {
     entries;
     customFieldNames;
     math;
+    /** Formatting defaults from the constructor; each call may override them. */
+    formatDefaults;
     constructor(options) {
         const bibData = maybeReadFile(options.data);
         this.customFieldNames = options.customFields ?? [];
+        this.formatDefaults = {
+            titleLink: options.titleLink,
+            badges: options.badges,
+            linkifyUrls: options.linkifyUrls,
+        };
         // Register CSL style
         this.templateName = this.registerStyle(options.cslStyle);
         // Two-pass parse: raw (preserves all fields) + CSL (for formatting)
@@ -81,14 +88,53 @@ export class Bibliography {
     // -------------------------------------------------------------------------
     /**
      * Format a single entry as an HTML string (no wrapper element).
-     * Applies title linking and badge injection.
+     * Applies title linking, badge injection and URL linkification.
      */
     formatEntry(entry, options = {}) {
+        const merged = this.mergeOptions(options);
         const rendered = this.renderCslEntries([entry]);
         const raw = rendered[0]?.[1] ?? "";
         const innerHtml = unwrapCslEntry(raw) ?? raw.trim();
-        const decorated = this.decorateEntryHtml(entry, innerHtml, options);
-        return this.math ? this.math.restore(decorated, options.renderMath) : decorated;
+        return this.buildEntryHtml(entry, innerHtml, merged);
+    }
+    /**
+     * Decorate, linkify and restore math for one rendered entry. Shared by
+     * `formatEntry` and `formatHtml` so both honour the same options.
+     *
+     * Linkification runs before math restoration: rendered MathML carries an
+     * xmlns URL that must not be turned into a link. Math is restored per entry
+     * so a failing formula can be reported with its citation key.
+     */
+    buildEntryHtml(entry, innerRaw, merged) {
+        let inner = this.decorateEntryHtml(entry, innerRaw, merged);
+        if (merged.linkifyUrls !== false)
+            inner = linkifyBareUrls(inner);
+        return this.restoreMath(inner, merged, entry);
+    }
+    /** Per-call options win over the defaults given to the constructor. */
+    mergeOptions(options) {
+        return {
+            ...options,
+            titleLink: options.titleLink ?? this.formatDefaults.titleLink,
+            badges: options.badges ?? this.formatDefaults.badges,
+            linkifyUrls: options.linkifyUrls ?? this.formatDefaults.linkifyUrls,
+        };
+    }
+    /**
+     * Restore protected math, naming the entry when a renderer rejects a formula.
+     * Without the citation key, `renderMath` failures are near-impossible to
+     * trace back to a line in the .bib file.
+     */
+    restoreMath(html, options, entry) {
+        if (!this.math)
+            return html;
+        try {
+            return this.math.restore(html, options.renderMath);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(entry ? `entry ${entry.key}: ${message}` : message, { cause: error });
+        }
     }
     /**
      * Format a list of entries as a complete HTML bibliography.
@@ -96,8 +142,9 @@ export class Bibliography {
     formatHtml(entries, options = {}) {
         if (entries.length === 0)
             return "";
-        const tag = options.list ?? "ol";
-        const attrs = options.listAttributes ?? (tag === "ol" ? { reversed: true } : {});
+        const merged = this.mergeOptions(options);
+        const tag = merged.list ?? "ol";
+        const attrs = merged.listAttributes ?? (tag === "ol" ? { reversed: true } : {});
         const attrStr = renderAttributes(attrs);
         // Render all entries in one citeproc run so style-dependent numbering/state
         // (e.g. vancouver left-margin labels) remains correct.
@@ -111,14 +158,10 @@ export class Bibliography {
                 ?? rendered[index]?.[1]
                 ?? "";
             const innerRaw = unwrapCslEntry(raw) ?? raw.trim();
-            const inner = this.decorateEntryHtml(entry, innerRaw, options);
+            const inner = this.buildEntryHtml(entry, innerRaw, merged);
             return `<${itemTag} data-csl-entry-id="${escapeAttr(entry.key)}" class="csl-entry">${inner}</${itemTag}>`;
         });
-        let html = `<${tag}${attrStr} class="csl-bib-body">\n${items.join("\n")}\n</${tag}>`;
-        if (options.linkifyUrls !== false) {
-            html = linkifyBareUrls(html);
-        }
-        return this.math ? this.math.restore(html, options.renderMath) : html;
+        return `<${tag}${attrStr} class="csl-bib-body">\n${items.join("\n")}\n</${tag}>`;
     }
     // -------------------------------------------------------------------------
     // Private helpers

package/dist/types.d.ts

@@ -45,14 +45,20 @@ export interface BadgeConfig {
 export type MathRenderer = (tex: string, context: {
     display: boolean;
 }) => string;
-/** Options passed to {@link Bibliography.formatHtml}. */
+/**
+ * Options passed to {@link Bibliography.formatHtml} or
+ * {@link Bibliography.formatEntry}. `list` and `listAttributes` only apply to
+ * `formatHtml`, which is the only method emitting a wrapper element.
+ */
 export interface FormatOptions {
     /** Render protected math as trusted HTML; requires preserveMath at construction.
      * Without this callback, escaped original TeX delimiters are restored.
+     * Not settable on the constructor.
      */
     renderMath?: MathRenderer;
     /**
      * Fields to use for linking the title, checked in order.
+     * Overrides the constructor default, if any.
      * A `doi` value is expanded to `https://doi.org/<value>`, an `arxiv`
      * value to `https://arxiv.org/abs/<value>`, and direct values are only
      * accepted when they use `http`, `https`, or `mailto`.
@@ -60,7 +66,12 @@ export interface FormatOptions {
      * @default ['url', 'doi', 'arxiv']
      */
     titleLink?: string[];
-    /** Badge configurations to append to each entry. */
+    /**
+     * Badge configurations to append to each entry.
+     * Overrides the constructor default, if any.
+     *
+     * @default [] (no badges)
+     */
     badges?: BadgeConfig[];
     /**
      * Wrapper list element.
@@ -77,6 +88,7 @@ export interface FormatOptions {
     /**
      * Auto-linkify bare `http(s)://` URLs in the rendered output that aren't
      * already inside `<a>`, `<script>`, or `<style>` tags.
+     * Overrides the constructor default, if any.
      *
      * @default true
      */
@@ -98,8 +110,13 @@ export interface BibEntry {
     /** The full raw BibTeX properties (unfiltered). */
     raw: Record<string, any>;
 }
+/**
+ * Formatting options that can be set once on the constructor and overridden
+ * by the options of an individual `formatHtml`/`formatEntry` call.
+ */
+export type FormatDefaults = Pick<FormatOptions, "titleLink" | "badges" | "linkifyUrls">;
 /** Options for constructing a {@link Bibliography}. */
-export interface BibliographyOptions {
+export interface BibliographyOptions extends FormatDefaults {
     /** Preserve math in supported display-text fields before CSL conversion.
      * Opt-in; entries' CSL text contains internal placeholders until HTML formatting.
      * Raw/custom fields remain unchanged. Unclosed or empty math throws.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@behackl/citation-js-extras",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Preserve custom BibTeX fields through citation-js and render academic bibliographies with linked titles, badges, and more.",
   "type": "module",
   "main": "./dist/index.js",