fix: server-side bibliography formatting and citation linking

- Add format-bibliography.ts: formats CSL-JSON entries server-side
using citation-js, independent of client-side renderedHtml
- Publisher now reads Y.Map("citations") and Y.Map("settings")
directly from the Y.Doc to build bibliography at publish time
- Inline citations are converted to clickable links pointing to
their bibliography entry (with :target highlighting)
- Supports both numeric (ieee/vancouver) and author-date styles
- Falls back to client-side renderedHtml if server formatting fails
- Add CSS for .citation-inline and .csl-entry:target

Made-with: Cursor

backend/src/publisher/format-bibliography.ts

@@ -0,0 +1,29 @@
+/**
+ * Server-side bibliography formatting using citation-js.
+ *
+ * Formats CSL-JSON entries into HTML bibliography, independent
+ * of any client-side rendering.
+ */
+
+import { Cite } from "@citation-js/core";
+import "@citation-js/plugin-bibtex";
+import "@citation-js/plugin-csl";
+
+/**
+ * Format an array of CSL-JSON entries into an HTML bibliography string.
+ */
+export async function formatBibliographyServer(
+  entries: any[],
+  style: string = "apa"
+): Promise<string> {
+  if (!entries.length) return "";
+
+  const cite = new Cite(entries);
+  const html = cite.format("bibliography", {
+    format: "html",
+    template: style,
+    lang: "en-US",
+  });
+
+  return html as string;
+}

backend/src/publisher/html-renderer.ts

@@ -34,21 +34,31 @@ export interface PublishMeta {
   pdfUrl?: string;
 }
 
+export interface CitationData {
+  entries: any[];
+  orderedKeys: string[];
+  style: string;
+}
+
 /**
  * Render TipTap JSON document into a complete, self-contained HTML page.
  */
 export function renderArticleHTML(
   json: Record<string, unknown>,
   meta: PublishMeta,
-  css: PublishCSS
+  css: PublishCSS,
+  citationData?: CitationData,
+  serverBiblioHtml?: string
 ): string {
   const extensions = getServerExtensions();
 
   // Extract bibliography HTML before generateHTML escapes it as an attribute
-  const biblioHtml = extractBibliographyHtml(json);
+  // (fallback to client-side renderedHtml if server formatting not available)
+  const clientBiblioHtml = extractBibliographyHtml(json);
+  const biblioHtml = serverBiblioHtml || clientBiblioHtml;
 
   const bodyHtml = generateHTML(json as any, extensions);
-  const enrichedBody = postProcess(bodyHtml, biblioHtml);
+  const enrichedBody = postProcess(bodyHtml, biblioHtml, citationData);
 
   const authorNames = meta.authors.map((a) => a.name);
   const authorsStr = authorNames.join(", ");
@@ -415,6 +425,32 @@ details[data-component="accordion"] > .accordion-content > *:last-child { margin
 .citation a { color: rgba(0, 0, 0, 0.6); text-decoration: underline; }
 .citation.short { margin-top: -4px; }
 
+.citation-inline {
+  color: var(--primary-color, #958df1);
+  text-decoration: none;
+  text-decoration-line: underline;
+  text-decoration-color: transparent;
+  text-underline-offset: 2px;
+  cursor: pointer;
+  transition: text-decoration-color 0.15s;
+}
+.citation-inline:hover {
+  text-decoration-color: currentColor;
+}
+
+.bibliography-content .csl-entry {
+  margin-bottom: 0.75em;
+  padding-left: 1.5em;
+  text-indent: -1.5em;
+  font-size: 0.9em;
+  line-height: 1.5;
+}
+.bibliography-content .csl-entry:target {
+  background: rgba(149, 141, 241, 0.1);
+  border-radius: 4px;
+  padding: 4px 4px 4px 1.5em;
+}
+
 .references-block .footer-heading { margin: 0; }
 .references-block ol { padding: 0 0 0 15px; }
 .references-block li { margin-bottom: 1em; }
@@ -443,6 +479,7 @@ details[data-component="accordion"] > .accordion-content > *:last-child { margin
 [data-theme="dark"] .footer { border-top-color: rgba(255, 255, 255, 0.15); color: rgba(200, 200, 200, 0.8); }
 [data-theme="dark"] .citation { background: rgba(255, 255, 255, 0.04); border-color: rgba(255, 255, 255, 0.15); color: rgba(200, 200, 200, 1); }
 [data-theme="dark"] .citation a { color: rgba(255, 255, 255, 0.75); }
+[data-theme="dark"] .bibliography-content .csl-entry:target { background: rgba(149, 141, 241, 0.15); }
 [data-theme="dark"] .footer a { color: var(--primary-color); }
 [data-theme="dark"] .template-credit p { color: rgba(200, 200, 200, 0.6); }
 [data-theme="dark"] .template-credit a { color: rgba(200, 200, 200, 0.7); border-bottom-color: rgba(255, 255, 255, 0.2); }
@@ -894,7 +931,7 @@ function extractBibliographyHtml(json: Record<string, unknown>): string {
  * - Transform accordion divs into <details><summary>
  * - Transform htmlEmbed into iframes
  */
-function postProcess(html: string, biblioHtml: string): string {
+function postProcess(html: string, biblioHtml: string, citationData?: CitationData): string {
   let result = html;
 
   // Accordion: div[data-component="accordion"] → <details><summary>
@@ -911,15 +948,46 @@ function postProcess(html: string, biblioHtml: string): string {
     }
   );
 
+  // Inline citations: replace <span data-type="citation" ...>label</span>
+  // with proper numbered links pointing to bibliography entries.
+  const NUMERIC_STYLES = new Set(["ieee", "vancouver"]);
+  const isNumeric = citationData ? NUMERIC_STYLES.has(citationData.style) : false;
+  const citationKeyOrder: string[] = [];
+
+  result = result.replace(
+    /<span[^>]*data-type="citation"[^>]*>[\s\S]*?<\/span>/g,
+    (match) => {
+      const keyMatch = match.match(/(?:\skey="|data-key=")([^"]*)"/);
+      if (!keyMatch) return match;
+      const key = keyMatch[1];
+
+      if (!citationKeyOrder.includes(key)) citationKeyOrder.push(key);
+      const idx = citationKeyOrder.indexOf(key) + 1;
+
+      // Extract the label text from the original HTML
+      const labelMatch = match.match(/>([^<]*)<\/span>/);
+      const originalLabel = labelMatch ? labelMatch[1] : `[${key}]`;
+
+      // For numeric styles, always use number; for author-date, keep original label
+      const displayLabel = isNumeric ? `[${idx}]` : originalLabel;
+
+      return `<a href="#ref-${escapeHtml(key)}" class="citation-inline" id="cite-${escapeHtml(key)}-${idx}" title="${escapeHtml(key)}">${displayLabel}</a>`;
+    }
+  );
+
   // Bibliography: replace empty placeholder with the pre-extracted HTML.
-  // renderedHtml was cleared before generateHTML, so the attribute is now
-  // empty and the div is clean (no > chars breaking the regex).
+  // Add id anchors to bibliography entries for citation linking.
   result = result.replace(
     /<div([^>]*data-type="bibliography"[^>]*)><\/div>/gi,
     (_match, attrs: string) => {
       const cleanAttrs = attrs.replace(/\s*renderedhtml="[^"]*"/i, "");
       if (biblioHtml) {
-        return `<div${cleanAttrs}><h2 class="bibliography-title">References</h2><div class="bibliography-content">${biblioHtml}</div></div>`;
+        // Wrap bibliography HTML with entry anchors
+        let enrichedBiblio = biblioHtml;
+        if (citationData && citationData.orderedKeys.length > 0) {
+          enrichedBiblio = addBibliographyAnchors(biblioHtml, citationData.orderedKeys);
+        }
+        return `<div${cleanAttrs}><h2 class="bibliography-title">References</h2><div class="bibliography-content">${enrichedBiblio}</div></div>`;
       }
       return `<div${cleanAttrs}><p class="bibliography-empty">No citations</p></div>`;
     }
@@ -977,6 +1045,23 @@ function postProcess(html: string, biblioHtml: string): string {
   return result;
 }
 
+/**
+ * Add id anchors to bibliography entries so inline citations can link to them.
+ * citation-js outputs entries as <div class="csl-entry"> elements.
+ * We wrap each one with an id matching the citation key.
+ */
+function addBibliographyAnchors(html: string, orderedKeys: string[]): string {
+  let idx = 0;
+  return html.replace(
+    /<div class="csl-entry">/g,
+    () => {
+      const key = orderedKeys[idx] || `entry-${idx}`;
+      idx++;
+      return `<div class="csl-entry" id="ref-${key}">`;
+    }
+  );
+}
+
 function escapeHtml(str: string): string {
   return str
     .replace(/&/g, "&amp;")

backend/src/publisher/index.ts

@@ -10,7 +10,8 @@ import { fileURLToPath } from "url";
 import * as Y from "yjs";
 import { DATA_DIR as SHARED_DATA_DIR, docPath } from "../utils.js";
 import { TiptapTransformer } from "@hocuspocus/transformer";
-import { renderArticleHTML, type PublishMeta } from "./html-renderer.js";
+import { renderArticleHTML, type PublishMeta, type CitationData } from "./html-renderer.js";
+import { formatBibliographyServer } from "./format-bibliography.js";
 import { getServerExtensions } from "./extensions.js";
 import { isPdfEnabled, generatePdfAndThumbnail } from "./pdf-generator.js";
 import {
@@ -187,6 +188,44 @@ function extractFromYDoc(ydoc: Y.Doc): {
   };
 }
 
+/**
+ * Extract citation entries and document order from Y.Doc.
+ */
+function extractCitationsFromYDoc(ydoc: Y.Doc, json: Record<string, unknown>): CitationData {
+  const citationsMap = ydoc.getMap("citations");
+  const settingsMap = ydoc.getMap("settings");
+
+  const style = (settingsMap.get("citationStyle") as string) || "apa";
+
+  // Collect all citation keys in document order
+  const orderedKeys: string[] = [];
+  function walkCitations(nodes: any[]) {
+    for (const node of nodes) {
+      if (node.type === "citation" && node.attrs?.key) {
+        const k = node.attrs.key as string;
+        if (!orderedKeys.includes(k)) orderedKeys.push(k);
+      }
+      if (Array.isArray(node.content)) walkCitations(node.content);
+    }
+  }
+  const content = (json as any)?.content;
+  if (Array.isArray(content)) walkCitations(content);
+
+  // Build entries list in document order
+  const entries: any[] = [];
+  for (const key of orderedKeys) {
+    const entry = citationsMap.get(key);
+    if (entry) {
+      entries.push({ ...(entry as any), id: key });
+    }
+  }
+
+  console.log("[publish] Citations from Y.Doc:", orderedKeys.length, "keys, style:", style);
+  console.log("[publish] Citation map size:", citationsMap.size);
+
+  return { entries, orderedKeys, style };
+}
+
 export interface PublishResult {
   htmlUrl: string | null;
   pdfUrl: string | null;
@@ -213,6 +252,9 @@ export async function publishDocument(docName: string, token?: string): Promise<
   // Extract content
   const { json, frontmatter, authors, affiliations } = extractFromYDoc(ydoc);
 
+  // Extract citation data from Y.Map for server-side bibliography formatting
+  const citationData = extractCitationsFromYDoc(ydoc, json);
+
   const meta: PublishMeta = {
     title: (frontmatter.title as string) || docName,
     subtitle: (frontmatter.subtitle as string) || undefined,
@@ -243,8 +285,19 @@ export async function publishDocument(docName: string, token?: string): Promise<
   console.log("[publish] CSS variables length:", css.variables.length, "article length:", css.article.length);
   console.log("[publish] Meta:", JSON.stringify(meta));
 
+  // Format bibliography server-side from citation entries
+  let biblioHtml = "";
+  if (citationData.entries.length > 0) {
+    try {
+      biblioHtml = await formatBibliographyServer(citationData.entries, citationData.style);
+      console.log("[publish] Bibliography formatted server-side:", citationData.entries.length, "entries");
+    } catch (err) {
+      console.error("[publish] Server-side bibliography formatting failed:", err);
+    }
+  }
+
   // First pass: generate HTML with og:image + PDF link pre-injected
-  let html = renderArticleHTML(json, meta, css);
+  let html = renderArticleHTML(json, meta, css, citationData, biblioHtml);
   console.log("[publish] Generated HTML length:", html.length);
 
   // Generate PDF + thumbnail from the HTML
@@ -261,7 +314,7 @@ export async function publishDocument(docName: string, token?: string): Promise<
       // Clear URLs from meta if generation failed
       if (!thumbnail) delete meta.ogImage;
       if (!pdf) delete meta.pdfUrl;
-      html = renderArticleHTML(json, meta, css);
+      html = renderArticleHTML(json, meta, css, citationData, biblioHtml);
     }
   }
 
@@ -277,7 +330,7 @@ export async function publishDocument(docName: string, token?: string): Promise<
   else delete localMeta.ogImage;
   if (pdf) localMeta.pdfUrl = `/published/${safeDirName}/article.pdf`;
   else delete localMeta.pdfUrl;
-  const localHtml = renderArticleHTML(json, localMeta, css);
+  const localHtml = renderArticleHTML(json, localMeta, css, citationData, biblioHtml);
 
   fsWrite(join(publishDir, "index.html"), localHtml);
   if (pdf) fsWrite(join(publishDir, "article.pdf"), pdf);