feat(publisher): generate llms.txt Markdown twin for LLM agents

External LLMs/agents (Claude, Perplexity, ...) struggle with the
heavy published HTML: theme bootstrap, KaTeX/Mermaid runtimes,
~7 inlined CSS files, TOC chrome, and D3 charts wrapped in
<iframe srcdoc>. The static research-article-template already
ships an `llms.txt` (Astro build plugin); the editor's publisher
now does the same, walking the TipTap-JSON we already extract
for the HTML/PDF pipeline.

Pipeline addition (publisher/index.ts):
- After writing index.html, render the same JSON to Markdown via
the new markdown-renderer.ts and write `published/<doc>/llms.txt`
- Re-render with the public HF meta and include it in the dataset
upload commit (hf-storage.ts adds llms.txt to the file list)

Routing (create-app.ts):
- GET /llms.txt serves the published Markdown twin with
Content-Type: text/markdown; charset=utf-8 (404 before publish)
- GET /robots.txt advertises it via the `LLMs-Txt:` header,
mirroring the upstream template

Conventions in the renderer mirror the upstream Astro plugin:
- HtmlEmbed -> *[Interactive visualization: <title|src>]*
- Note/Sidenote -> blockquote
- QuoteBlock -> blockquote + author/source attribution
- Wide/FullWidth/Stack -> unwrap content
- Accordion -> bold title + content
- Mermaid -> ```mermaid fenced block
- HfUser -> [name](https://huggingface.co/<u>)
- Citations -> key (APA) or [N] (IEEE/Vancouver)
- Footnotes -> Pandoc [^N] + footnotes section
- Bibliography -> stripped to plain text in a References section
- Inline/block math kept as $...$ / $$...$$

22 new unit tests cover header, blocks, custom components,
citations/footnotes, and the HTML stripper helper. All 87
backend tests pass; tsc clean on backend and frontend.

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -26,7 +26,7 @@ A collaborative, real-time editor for web-native scientific articles. It lets mu
 - **Comments & discussion** anchored on any selection
 - **Slash menu** (`/`) and drag/drop block handles, in the spirit of Notion
 - **Click-to-edit frontmatter**: title, subtitle, authors, affiliations, links, banner color
-- **Publishing pipeline**: one-click export to a standalone static HTML bundle, plus PDF generation (Puppeteer)
+- **Publishing pipeline**: one-click export to a standalone static HTML bundle, plus PDF generation (Puppeteer) and an `llms.txt` Markdown twin for LLM agents/crawlers (served at `/llms.txt`, advertised in `/robots.txt`)
 - **Persistence**:
   - Local mode: documents stored on disk under `DATA_DIR`
   - HF mode: documents pushed/pulled from a Hugging Face dataset via OAuth

backend/src/create-app.ts

@@ -307,9 +307,44 @@ export function createApp() {
     return join(DATA_DIR, "published", docName, "index.html");
   }
 
+  function getPublishedAssetPath(docName: string, filename: string): string {
+    return join(DATA_DIR, "published", docName, filename);
+  }
+
   if (existsSync(staticDir)) {
     app.use(express.static(staticDir, { index: false }));
 
+    // ---- LLM-friendly endpoints --------------------------------------
+    // The publisher generates a Markdown twin of the article (`llms.txt`)
+    // following the https://llmstxt.org/ convention. We expose it at the
+    // Space root so external agents/crawlers (Claude, Perplexity, ...) can
+    // consume the article without having to parse the heavy HTML page.
+    // `robots.txt` advertises this endpoint.
+
+    app.get("/llms.txt", async (_req, res) => {
+      const llmsPath = getPublishedAssetPath(DEFAULT_DOC_NAME, "llms.txt");
+      if (!existsSync(llmsPath)) {
+        res.status(404).type("text/plain").send("Not yet published");
+        return;
+      }
+      res.type("text/markdown; charset=utf-8");
+      res.sendFile(llmsPath);
+    });
+
+    app.get("/robots.txt", (_req, res) => {
+      res
+        .type("text/plain; charset=utf-8")
+        .send(
+          [
+            "User-agent: *",
+            "Allow: /",
+            "",
+            "LLMs-Txt: /llms.txt",
+            "",
+          ].join("\n"),
+        );
+    });
+
     app.get("/editor", async (req, res) => {
       if (oauthEnabled) {
         const { resolveUser } = await import("./auth.js");

backend/src/hf-storage.ts

@@ -157,7 +157,7 @@ export async function pullPublishedAssets(
 
   const safeName = sanitizeName(docName);
   const base = `published/${safeName}`;
-  const files = ["index.html", "article.pdf", "thumb.jpg", "meta.json"];
+  const files = ["index.html", "article.pdf", "thumb.jpg", "meta.json", "llms.txt"];
 
   const { mkdirSync, writeFileSync } = await import("fs");
   const { join } = await import("path");
@@ -226,6 +226,7 @@ interface PublishedPayload {
   pdf: Buffer | null;
   thumbnail: Buffer | null;
   meta: { title: string; description: string; authors: string[]; date: string; [key: string]: unknown };
+  llmsTxt?: string;
 }
 
 export async function uploadPublishedAssets(
@@ -274,6 +275,14 @@ export async function uploadPublishedAssets(
     thumbUrl = `${baseUrl}/thumb.jpg`;
   }
 
+  if (payload.llmsTxt) {
+    operations.push({
+      operation: "addOrUpdate",
+      path: `${base}/llms.txt`,
+      content: new Blob([payload.llmsTxt], { type: "text/markdown; charset=utf-8" }),
+    });
+  }
+
   await commit({
     repo,
     operations,

backend/src/publisher/index.ts

@@ -11,6 +11,7 @@ import * as Y from "yjs";
 import { getDataDir, docPath, sanitizeName } from "../utils.js";
 import { TiptapTransformer } from "@hocuspocus/transformer";
 import { renderArticleHTML, type PublishMeta, type CitationData } from "./html-renderer.js";
+import { renderArticleMarkdown } from "./markdown-renderer.js";
 import { formatBibliographyServer } from "./format-bibliography.js";
 import { getServerExtensions } from "./extensions.js";
 import { isPdfEnabled, generatePdfAndThumbnail } from "./pdf-generator.js";
@@ -435,6 +436,18 @@ export async function publishDocument(
   fsMkdir(publishDir, { recursive: true });
   fsWrite(join(publishDir, "index.html"), localHtml);
   fsWrite(join(publishDir, "meta.json"), JSON.stringify(localMeta, null, 2));
+
+  // Co-located `llms.txt` (https://llmstxt.org/) for LLM agents and
+  // crawlers that struggle with the heavy published HTML. Cheap to
+  // generate (one walk over the same TipTap-JSON, no Playwright) so we
+  // always write it; serving is gated separately by `create-app.ts`.
+  let llmsTxt = "";
+  try {
+    llmsTxt = renderArticleMarkdown(json, localMeta, citationData, biblioHtml);
+    fsWrite(join(publishDir, "llms.txt"), llmsTxt);
+  } catch (err) {
+    console.warn("[publish] llms.txt generation failed:", (err as Error).message);
+  }
   console.log("[publish] index.html written to", publishDir);
 
   // --- Step 2: generate PDF + thumbnail from the served URL ---------------
@@ -487,11 +500,21 @@ export async function publishDocument(
     if (pdf) hfMeta.pdfUrl = getPublishedAssetUrl(docName, "article.pdf");
     const hfHtml = await renderArticleHTML(json, hfMeta, css, citationData, biblioHtml, embeds);
     try {
+      // Re-render llms.txt with the HF meta so internal links (DOI, etc.)
+      // match what's in the uploaded HTML. Cheap, deterministic, and we
+      // already have everything in memory.
+      let hfLlmsTxt: string | undefined = undefined;
+      try {
+        hfLlmsTxt = renderArticleMarkdown(json, hfMeta, citationData, biblioHtml);
+      } catch (err) {
+        console.warn("[publish] HF llms.txt render failed:", (err as Error).message);
+      }
       const urls = await uploadPublishedAssets(docName, {
         html: hfHtml,
         pdf,
         thumbnail,
         meta: hfMeta as any,
+        llmsTxt: hfLlmsTxt,
       }, token);
       return { ...urls, success: true };
     } catch (err) {

backend/src/publisher/markdown-renderer.ts

@@ -0,0 +1,496 @@
+/**
+ * Server-side Markdown renderer for the publisher pipeline.
+ *
+ * Walks the same TipTap-JSON document used by `html-renderer.ts` and
+ * produces a clean Markdown file conforming to the `llms.txt` convention
+ * (https://llmstxt.org/). The output is meant to be consumed by LLM
+ * agents and crawlers that struggle with the heavy published HTML
+ * (theme bootstrap, KaTeX/Mermaid runtimes, inlined CSS, iframe-wrapped
+ * D3 charts, ...).
+ *
+ * Conventions mirror the upstream `research-article-template` Astro
+ * plugin (`app/plugins/astro/generate-llms-txt.mjs`):
+ *
+ *   - `<HtmlEmbed src="..." />` -> `*[Interactive visualization: <src>]*`
+ *   - `<Note>...</Note>`        -> blockquote
+ *   - `<Quote author=...>`      -> blockquote + attribution
+ *   - `<Wide>`/`<FullWidth>`    -> unwrap content
+ *   - `<Sidenote>`              -> main content + blockquote aside
+ *   - `<Reference caption=...>` -> content + caption
+ *   - `<Accordion title=...>`   -> bold title + content
+ *   - `<Mermaid code=...>`      -> fenced ```mermaid``` code block
+ *   - `<HfUser username=...>`   -> `[@u](https://huggingface.co/u)`
+ *   - `<Citation key=...>`      -> `[key]` (or `[N]` for IEEE)
+ *   - `<Footnote content=...>`  -> Pandoc `[^N]` reference + footnotes section
+ *   - inline / block math       -> `$...$` / `$$...$$`
+ *
+ * Output shape:
+ *   # <title>
+ *
+ *   > <subtitle / description>
+ *
+ *   - **Authors**: ...
+ *   - **Published**: ...
+ *   - **DOI**: ...
+ *
+ *   ---
+ *
+ *   <body markdown>
+ *
+ *   ## References
+ *   ...
+ *
+ *   ## Footnotes
+ *   ...
+ */
+
+import type { PublishMeta, CitationData } from "./html-renderer.js";
+
+type JSONNode = {
+  type?: string;
+  attrs?: Record<string, any>;
+  marks?: Array<{ type: string; attrs?: Record<string, any> }>;
+  text?: string;
+  content?: JSONNode[];
+};
+
+interface RenderCtx {
+  citationData?: CitationData;
+  /** Pre-formatted bibliography (HTML from citation-js) - we strip tags. */
+  biblioHtml?: string;
+  /** Footnote texts collected during the walk, emitted at the end. */
+  footnotes: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Inline rendering (text + marks + inline atoms)
+// ---------------------------------------------------------------------------
+
+function applyMarks(text: string, marks: JSONNode["marks"]): string {
+  if (!marks?.length) return text;
+  let out = text;
+  for (const mark of marks) {
+    switch (mark.type) {
+      case "bold":
+        out = `**${out}**`;
+        break;
+      case "italic":
+        out = `*${out}*`;
+        break;
+      case "strike":
+        out = `~~${out}~~`;
+        break;
+      case "code":
+        out = `\`${out}\``;
+        break;
+      case "link": {
+        const href = mark.attrs?.href || "";
+        out = href ? `[${out}](${href})` : out;
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  return out;
+}
+
+function getCitationLabel(key: string, ctx: RenderCtx, fallbackLabel?: string): string {
+  if (!ctx.citationData) return fallbackLabel || `[${key}]`;
+  const { style, orderedKeys } = ctx.citationData;
+  if (style === "ieee" || style === "vancouver") {
+    const idx = orderedKeys.indexOf(key);
+    if (idx >= 0) return `[${idx + 1}]`;
+  }
+  return fallbackLabel || `[${key}]`;
+}
+
+function renderInline(nodes: JSONNode[] | undefined, ctx: RenderCtx): string {
+  if (!nodes) return "";
+  let out = "";
+  for (const node of nodes) {
+    out += renderInlineNode(node, ctx);
+  }
+  return out;
+}
+
+function renderInlineNode(node: JSONNode, ctx: RenderCtx): string {
+  switch (node.type) {
+    case "text":
+      return applyMarks(node.text || "", node.marks);
+    case "hardBreak":
+      return "  \n";
+    case "inlineMath": {
+      const latex = node.attrs?.latex || "";
+      return latex ? `$${latex}$` : "";
+    }
+    case "citation": {
+      const key = String(node.attrs?.key || "");
+      if (!key) return "";
+      return getCitationLabel(key, ctx, node.attrs?.label);
+    }
+    case "glossary": {
+      const term = String(node.attrs?.term || "");
+      return term;
+    }
+    case "footnote": {
+      const content = String(node.attrs?.content || "");
+      ctx.footnotes.push(content);
+      return `[^${ctx.footnotes.length}]`;
+    }
+    case "image": {
+      const src = String(node.attrs?.src || "");
+      const alt = String(node.attrs?.alt || "");
+      const title = node.attrs?.title ? ` "${node.attrs.title}"` : "";
+      return src ? `![${alt}](${src}${title})` : alt;
+    }
+    default:
+      // Unknown inline: fall back to its text content if any.
+      return renderInline(node.content, ctx);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Block rendering
+// ---------------------------------------------------------------------------
+
+function renderBlocks(nodes: JSONNode[] | undefined, ctx: RenderCtx): string {
+  if (!nodes?.length) return "";
+  const parts: string[] = [];
+  for (const node of nodes) {
+    const rendered = renderBlock(node, ctx);
+    if (rendered) parts.push(rendered);
+  }
+  return parts.join("\n\n");
+}
+
+function renderBlock(node: JSONNode, ctx: RenderCtx): string {
+  switch (node.type) {
+    case "doc":
+      return renderBlocks(node.content, ctx);
+
+    case "paragraph": {
+      const inner = renderInline(node.content, ctx).trim();
+      return inner;
+    }
+
+    case "heading": {
+      const level = Math.min(Math.max(Number(node.attrs?.level) || 1, 1), 6);
+      const inner = renderInline(node.content, ctx).trim();
+      return `${"#".repeat(level)} ${inner}`;
+    }
+
+    case "blockquote": {
+      const inner = renderBlocks(node.content, ctx);
+      return inner
+        .split("\n")
+        .map((l) => (l.length ? `> ${l}` : ">"))
+        .join("\n");
+    }
+
+    case "horizontalRule":
+      return "---";
+
+    case "codeBlock": {
+      const lang = String(node.attrs?.language || node.attrs?.lang || "");
+      const code = (node.content || [])
+        .map((c) => c.text || "")
+        .join("");
+      return `\`\`\`${lang}\n${code}\n\`\`\``;
+    }
+
+    case "bulletList":
+      return renderList(node, ctx, "-");
+
+    case "orderedList":
+      return renderList(node, ctx, "1.");
+
+    case "listItem": {
+      // Should normally be reached via renderList, but if encountered
+      // standalone we just render its blocks.
+      return renderBlocks(node.content, ctx);
+    }
+
+    case "blockMath": {
+      const latex = String(node.attrs?.latex || "").trim();
+      return latex ? `$$\n${latex}\n$$` : "";
+    }
+
+    case "table":
+      return renderTable(node, ctx);
+
+    // --- Custom block components ---
+
+    case "accordion": {
+      const title = String(node.attrs?.title || "Details");
+      const inner = renderBlocks(node.content, ctx);
+      return `**${title}**\n\n${inner}`;
+    }
+
+    case "note": {
+      const inner = renderBlocks(node.content, ctx);
+      return inner
+        .split("\n")
+        .map((l) => (l.length ? `> ${l}` : ">"))
+        .join("\n");
+    }
+
+    case "quoteBlock": {
+      const inner = renderBlocks(node.content, ctx);
+      const author = String(node.attrs?.author || "").trim();
+      const source = String(node.attrs?.source || "").trim();
+      const attribution = [author, source].filter(Boolean).join(", ");
+      const quoted = inner
+        .split("\n")
+        .map((l) => (l.length ? `> ${l}` : ">"))
+        .join("\n");
+      return attribution ? `${quoted}\n>\n> -- ${attribution}` : quoted;
+    }
+
+    case "wide":
+    case "fullWidth":
+    case "stack":
+    case "stackColumn":
+      return renderBlocks(node.content, ctx);
+
+    case "sidenote": {
+      const inner = renderBlocks(node.content, ctx);
+      // No `slot="aside"` in TipTap-JSON: render as a blockquote.
+      return inner
+        .split("\n")
+        .map((l) => (l.length ? `> ${l}` : ">"))
+        .join("\n");
+    }
+
+    case "reference": {
+      const inner = renderBlocks(node.content, ctx);
+      const caption = String(node.attrs?.caption || "").trim();
+      return caption ? `${inner}\n\n*Figure: ${caption}*` : inner;
+    }
+
+    case "htmlEmbed": {
+      const src = String(node.attrs?.src || "").trim();
+      const title = String(node.attrs?.title || "").trim();
+      const desc = String(node.attrs?.desc || "").trim();
+      const labelParts = [title, desc].filter(Boolean);
+      const label = labelParts.length
+        ? labelParts.join(" - ")
+        : src || "embed";
+      return `*[Interactive visualization: ${label}]*`;
+    }
+
+    case "hfUser": {
+      const username = String(node.attrs?.username || "").trim();
+      if (!username) return "";
+      const url =
+        String(node.attrs?.url || "").trim() ||
+        `https://huggingface.co/${encodeURIComponent(username)}`;
+      const name = String(node.attrs?.name || "").trim() || `@${username}`;
+      return `[${name}](${url})`;
+    }
+
+    case "rawHtml": {
+      const html = String(node.attrs?.html || "");
+      return stripHtmlToText(html).trim();
+    }
+
+    case "mermaid": {
+      const code = String(node.attrs?.code || "").trim();
+      return code ? `\`\`\`mermaid\n${code}\n\`\`\`` : "";
+    }
+
+    case "bibliography":
+      // Emitted by `appendBibliographySection` from the post-walk step.
+      return "";
+
+    default:
+      // Unknown block: fall back to its content, or empty.
+      return renderBlocks(node.content, ctx);
+  }
+}
+
+function renderList(
+  node: JSONNode,
+  ctx: RenderCtx,
+  marker: string,
+): string {
+  const items = node.content || [];
+  const lines: string[] = [];
+  items.forEach((item, idx) => {
+    const innerBlocks = renderBlocks(item.content, ctx);
+    const prefix = marker === "1." ? `${idx + 1}.` : marker;
+    const innerLines = innerBlocks.split("\n");
+    lines.push(`${prefix} ${innerLines[0] ?? ""}`);
+    for (let i = 1; i < innerLines.length; i++) {
+      const indent = " ".repeat(prefix.length + 1);
+      lines.push(`${indent}${innerLines[i]}`);
+    }
+  });
+  return lines.join("\n");
+}
+
+function renderTable(node: JSONNode, ctx: RenderCtx): string {
+  const rows = node.content || [];
+  if (!rows.length) return "";
+
+  const grid: string[][] = [];
+  let headerRowIndex = -1;
+
+  for (let r = 0; r < rows.length; r++) {
+    const row = rows[r];
+    const cells = row.content || [];
+    const rowText: string[] = [];
+    let rowIsHeader = false;
+    for (const cell of cells) {
+      if (cell.type === "tableHeader") rowIsHeader = true;
+      const text = renderBlocks(cell.content, ctx)
+        .replace(/\n+/g, " ")
+        .replace(/\|/g, "\\|")
+        .trim();
+      rowText.push(text);
+    }
+    grid.push(rowText);
+    if (rowIsHeader && headerRowIndex === -1) headerRowIndex = r;
+  }
+
+  const colCount = Math.max(...grid.map((r) => r.length));
+  for (const row of grid) {
+    while (row.length < colCount) row.push("");
+  }
+
+  const lines: string[] = [];
+  if (headerRowIndex === -1) {
+    // No explicit header row: synthesize one with empty cells so the
+    // markdown table is still valid.
+    lines.push(`| ${new Array(colCount).fill(" ").join(" | ")} |`);
+    lines.push(`| ${new Array(colCount).fill("---").join(" | ")} |`);
+    for (const row of grid) lines.push(`| ${row.join(" | ")} |`);
+  } else {
+    for (let r = 0; r < grid.length; r++) {
+      lines.push(`| ${grid[r].join(" | ")} |`);
+      if (r === headerRowIndex) {
+        lines.push(`| ${new Array(colCount).fill("---").join(" | ")} |`);
+      }
+    }
+  }
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Header (frontmatter) + bibliography + footnotes
+// ---------------------------------------------------------------------------
+
+function buildHeader(meta: PublishMeta): string {
+  const titleClean = (meta.title || "Untitled")
+    .replace(/\\n/g, " ")
+    .replace(/\n/g, " ")
+    .replace(/\s{2,}/g, " ")
+    .trim();
+
+  const parts = [`# ${titleClean}\n`];
+
+  const desc = (meta.description || meta.subtitle || "").trim();
+  if (desc) parts.push(`> ${desc}\n`);
+
+  const metaLines: string[] = [];
+  const authors = meta.authors.map((a) => a.name).filter(Boolean);
+  if (authors.length) metaLines.push(`- **Authors**: ${authors.join(", ")}`);
+  if (meta.date) metaLines.push(`- **Published**: ${meta.date}`);
+  if (meta.doi) {
+    const doiUrl = meta.doi.startsWith("http")
+      ? meta.doi
+      : `https://doi.org/${meta.doi}`;
+    metaLines.push(`- **DOI**: ${doiUrl}`);
+  }
+  if (metaLines.length) parts.push(metaLines.join("\n") + "\n");
+
+  parts.push("---\n");
+  return parts.join("\n");
+}
+
+function appendBibliographySection(
+  ctx: RenderCtx,
+): string {
+  if (!ctx.biblioHtml) return "";
+  const text = stripHtmlToText(ctx.biblioHtml).trim();
+  if (!text) return "";
+  return `## References\n\n${text}`;
+}
+
+function appendFootnotesSection(ctx: RenderCtx): string {
+  if (!ctx.footnotes.length) return "";
+  const lines = ctx.footnotes.map((content, i) => {
+    const clean = stripHtmlToText(content).trim().replace(/\n+/g, " ");
+    return `[^${i + 1}]: ${clean}`;
+  });
+  return `## Footnotes\n\n${lines.join("\n\n")}`;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Strip HTML tags while keeping anchor hrefs as Markdown links and emitting
+ * a blank line between block-level elements. Tuned for citation-js HTML
+ * output and for `rawHtml` user content - not a general-purpose sanitiser.
+ */
+export function stripHtmlToText(html: string): string {
+  if (!html) return "";
+  let out = html;
+  out = out.replace(/<a\s+[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi, "[$2]($1)");
+  out = out.replace(/<br\s*\/?>/gi, "\n");
+  out = out.replace(
+    /<\/(p|div|li|tr|h[1-6])>/gi,
+    "$&\n",
+  );
+  out = out.replace(/<[^>]+>/g, "");
+  out = out
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'");
+  return out
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l, i, arr) => !(l === "" && arr[i - 1] === ""))
+    .join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Render a TipTap-JSON document into an `llms.txt`-compatible Markdown string.
+ *
+ * `serverBiblioHtml` is the same HTML produced by `formatBibliographyServer()`
+ * for the HTML pipeline; we reuse it (stripped to text) so the agent gets the
+ * same reference list a human would see.
+ */
+export function renderArticleMarkdown(
+  json: Record<string, unknown>,
+  meta: PublishMeta,
+  citationData?: CitationData,
+  serverBiblioHtml?: string,
+): string {
+  const ctx: RenderCtx = {
+    citationData,
+    biblioHtml: serverBiblioHtml,
+    footnotes: [],
+  };
+
+  const body = renderBlocks((json as JSONNode).content, ctx);
+  const header = buildHeader(meta);
+  const refs = appendBibliographySection(ctx);
+  const footnotes = appendFootnotesSection(ctx);
+
+  const sections = [header.trimEnd(), body, refs, footnotes]
+    .filter(Boolean)
+    .join("\n\n");
+
+  return sections.replace(/\n{3,}/g, "\n\n").trim() + "\n";
+}

backend/tests/markdown-renderer.test.ts

@@ -0,0 +1,371 @@
+import { describe, it, expect } from "vitest";
+import {
+  renderArticleMarkdown,
+  stripHtmlToText,
+} from "../src/publisher/markdown-renderer.js";
+import type { PublishMeta, CitationData } from "../src/publisher/html-renderer.js";
+
+const META: PublishMeta = {
+  title: "Test Article",
+  subtitle: "A subtitle",
+  description: "A short description for SEO",
+  authors: [
+    { name: "Alice", affiliationIndices: [1], affiliationNames: ["MIT"] },
+    { name: "Bob", affiliationIndices: [2], affiliationNames: ["HF"] },
+  ],
+  affiliations: [{ name: "MIT" }, { name: "HF" }],
+  date: "2026-04-30",
+  doi: "10.1234/abcd.efgh",
+};
+
+const doc = (content: any[]) => ({ type: "doc", content });
+
+describe("renderArticleMarkdown - header", () => {
+  it("emits an llms.txt-style header with title, description, authors, date and DOI", () => {
+    const md = renderArticleMarkdown(doc([{ type: "paragraph" }]), META);
+    expect(md).toContain("# Test Article");
+    expect(md).toContain("> A short description for SEO");
+    expect(md).toContain("- **Authors**: Alice, Bob");
+    expect(md).toContain("- **Published**: 2026-04-30");
+    expect(md).toContain("- **DOI**: https://doi.org/10.1234/abcd.efgh");
+    expect(md).toContain("---");
+  });
+
+  it("falls back to subtitle when description is empty", () => {
+    const md = renderArticleMarkdown(
+      doc([{ type: "paragraph" }]),
+      { ...META, description: "" },
+    );
+    expect(md).toContain("> A subtitle");
+  });
+
+  it("collapses multi-line titles", () => {
+    const md = renderArticleMarkdown(
+      doc([{ type: "paragraph" }]),
+      { ...META, title: "Line one\\nLine two" },
+    );
+    expect(md).toContain("# Line one Line two");
+    expect(md).not.toContain("\\n");
+  });
+});
+
+describe("renderArticleMarkdown - block nodes", () => {
+  it("renders headings with the correct markdown level", () => {
+    const md = renderArticleMarkdown(
+      doc([
+        { type: "heading", attrs: { level: 2 }, content: [{ type: "text", text: "Hello" }] },
+        { type: "heading", attrs: { level: 3 }, content: [{ type: "text", text: "Sub" }] },
+      ]),
+      META,
+    );
+    expect(md).toContain("## Hello");
+    expect(md).toContain("### Sub");
+  });
+
+  it("applies bold/italic/code/link marks", () => {
+    const md = renderArticleMarkdown(
+      doc([
+        {
+          type: "paragraph",
+          content: [
+            { type: "text", text: "bold", marks: [{ type: "bold" }] },
+            { type: "text", text: " " },
+            { type: "text", text: "italic", marks: [{ type: "italic" }] },
+            { type: "text", text: " " },
+            { type: "text", text: "code", marks: [{ type: "code" }] },
+            { type: "text", text: " " },
+            {
+              type: "text",
+              text: "link",
+              marks: [{ type: "link", attrs: { href: "https://example.com" } }],
+            },
+          ],
+        },
+      ]),
+      META,
+    );
+    expect(md).toContain("**bold**");
+    expect(md).toContain("*italic*");
+    expect(md).toContain("`code`");
+    expect(md).toContain("[link](https://example.com)");
+  });
+
+  it("renders bullet and ordered lists", () => {
+    const md = renderArticleMarkdown(
+      doc([
+        {
+          type: "bulletList",
+          content: [
+            { type: "listItem", content: [{ type: "paragraph", content: [{ type: "text", text: "one" }] }] },
+            { type: "listItem", content: [{ type: "paragraph", content: [{ type: "text", text: "two" }] }] },
+          ],
+        },
+        {
+          type: "orderedList",
+          content: [
+            { type: "listItem", content: [{ type: "paragraph", content: [{ type: "text", text: "first" }] }] },
+            { type: "listItem", content: [{ type: "paragraph", content: [{ type: "text", text: "second" }] }] },
+          ],
+        },
+      ]),
+      META,
+    );
+    expect(md).toContain("- one");
+    expect(md).toContain("- two");
+    expect(md).toContain("1. first");
+    expect(md).toContain("2. second");
+  });
+
+  it("renders code blocks with language fence", () => {
+    const md = renderArticleMarkdown(
+      doc([
+        {
+          type: "codeBlock",
+          attrs: { language: "ts" },
+          content: [{ type: "text", text: "const x = 1;" }],
+        },
+      ]),
+      META,
+    );
+    expect(md).toContain("```ts");
+    expect(md).toContain("const x = 1;");
+    expect(md).toContain("```");
+  });
+
+  it("renders inline and block math", () => {
+    const md = renderArticleMarkdown(
+      doc([
+        {
+          type: "paragraph",
+          content: [
+            { type: "text", text: "Energy: " },
+            { type: "inlineMath", attrs: { latex: "E = mc^2" } },
+          ],
+        },
+        { type: "blockMath", attrs: { latex: "\\int_0^1 x dx" } },
+      ]),
+      META,
+    );
+    expect(md).toContain("$E = mc^2$");
+    expect(md).toContain("$$\n\\int_0^1 x dx\n$$");
+  });
+
+  it("renders tables with a header row separator", () => {
+    const md = renderArticleMarkdown(
+      doc([
+        {
+          type: "table",
+          content: [
+            {
+              type: "tableRow",
+              content: [
+                { type: "tableHeader", content: [{ type: "paragraph", content: [{ type: "text", text: "Col A" }] }] },
+                { type: "tableHeader", content: [{ type: "paragraph", content: [{ type: "text", text: "Col B" }] }] },
+              ],
+            },
+            {
+              type: "tableRow",
+              content: [
+                { type: "tableCell", content: [{ type: "paragraph", content: [{ type: "text", text: "1" }] }] },
+                { type: "tableCell", content: [{ type: "paragraph", content: [{ type: "text", text: "2" }] }] },
+              ],
+            },
+          ],
+        },
+      ]),
+      META,
+    );
+    expect(md).toContain("| Col A | Col B |");
+    expect(md).toContain("| --- | --- |");
+    expect(md).toContain("| 1 | 2 |");
+  });
+});
+
+describe("renderArticleMarkdown - custom components", () => {
+  it("collapses HtmlEmbed to a single inline placeholder with title and src", () => {
+    const md = renderArticleMarkdown(
+      doc([
+        {
+          type: "htmlEmbed",
+          attrs: { src: "d3-chart.html", title: "Citations over time", desc: "" },
+        },
+      ]),
+      META,
+    );
+    expect(md).toContain("*[Interactive visualization: Citations over time]*");
+    expect(md).not.toContain("<iframe");
+  });
+
+  it("renders Note as a blockquote", () => {
+    const md = renderArticleMarkdown(
+      doc([
+        {
+          type: "note",
+          content: [
+            { type: "paragraph", content: [{ type: "text", text: "Heads up." }] },
+          ],
+        },
+      ]),
+      META,
+    );
+    expect(md).toContain("> Heads up.");
+  });
+
+  it("renders Accordion with bold title and inner content", () => {
+    const md = renderArticleMarkdown(
+      doc([
+        {
+          type: "accordion",
+          attrs: { title: "More details" },
+          content: [
+            { type: "paragraph", content: [{ type: "text", text: "Inside." }] },
+          ],
+        },
+      ]),
+      META,
+    );
+    expect(md).toContain("**More details**");
+    expect(md).toContain("Inside.");
+  });
+
+  it("renders QuoteBlock with attribution", () => {
+    const md = renderArticleMarkdown(
+      doc([
+        {
+          type: "quoteBlock",
+          attrs: { author: "Ada Lovelace", source: "Notes" },
+          content: [
+            { type: "paragraph", content: [{ type: "text", text: "The future is open." }] },
+          ],
+        },
+      ]),
+      META,
+    );
+    expect(md).toContain("> The future is open.");
+    expect(md).toContain("> -- Ada Lovelace, Notes");
+  });
+
+  it("renders HfUser as a markdown link to huggingface.co/<u>", () => {
+    const md = renderArticleMarkdown(
+      doc([
+        {
+          type: "hfUser",
+          attrs: { username: "tfrere", name: "Thibaud Frere" },
+        },
+      ]),
+      META,
+    );
+    expect(md).toContain("[Thibaud Frere](https://huggingface.co/tfrere)");
+  });
+
+  it("renders Mermaid as a fenced ```mermaid block", () => {
+    const md = renderArticleMarkdown(
+      doc([
+        {
+          type: "mermaid",
+          attrs: { code: "graph TD\n  A --> B" },
+        },
+      ]),
+      META,
+    );
+    expect(md).toContain("```mermaid");
+    expect(md).toContain("graph TD");
+    expect(md).toContain("A --> B");
+  });
+
+  it("unwraps Wide / FullWidth / Stack containers", () => {
+    const md = renderArticleMarkdown(
+      doc([
+        {
+          type: "wide",
+          content: [
+            { type: "paragraph", content: [{ type: "text", text: "Wide content." }] },
+          ],
+        },
+      ]),
+      META,
+    );
+    expect(md).toContain("Wide content.");
+    expect(md).not.toContain("[wide]");
+  });
+});
+
+describe("renderArticleMarkdown - citations and footnotes", () => {
+  it("renders citations as keys for APA and as numeric tags for IEEE", () => {
+    const json = doc([
+      {
+        type: "paragraph",
+        content: [
+          { type: "text", text: "See " },
+          { type: "citation", attrs: { key: "smith2024", label: "Smith (2024)" } },
+          { type: "text", text: "." },
+        ],
+      },
+    ]);
+    const apa: CitationData = {
+      entries: [{ id: "smith2024" }],
+      orderedKeys: ["smith2024"],
+      style: "apa",
+    };
+    const ieee: CitationData = {
+      entries: [{ id: "smith2024" }],
+      orderedKeys: ["smith2024"],
+      style: "ieee",
+    };
+    expect(renderArticleMarkdown(json, META, apa)).toContain("Smith (2024)");
+    expect(renderArticleMarkdown(json, META, ieee)).toContain("[1]");
+  });
+
+  it("collects footnotes and emits a footnotes section", () => {
+    const md = renderArticleMarkdown(
+      doc([
+        {
+          type: "paragraph",
+          content: [
+            { type: "text", text: "Body" },
+            { type: "footnote", attrs: { content: "First note" } },
+            { type: "text", text: " more " },
+            { type: "footnote", attrs: { content: "Second note" } },
+          ],
+        },
+      ]),
+      META,
+    );
+    expect(md).toContain("[^1]");
+    expect(md).toContain("[^2]");
+    expect(md).toContain("## Footnotes");
+    expect(md).toContain("[^1]: First note");
+    expect(md).toContain("[^2]: Second note");
+  });
+
+  it("appends a References section from the formatted bibliography", () => {
+    const biblio = '<div class="csl-entry">Smith, J. (2024). <i>Test Paper</i>. Journal.</div>';
+    const md = renderArticleMarkdown(
+      doc([{ type: "paragraph", content: [{ type: "text", text: "Body" }] }]),
+      META,
+      undefined,
+      biblio,
+    );
+    expect(md).toContain("## References");
+    expect(md).toContain("Smith, J. (2024).");
+    expect(md).toContain("Test Paper");
+    expect(md).not.toContain("<div");
+  });
+});
+
+describe("stripHtmlToText", () => {
+  it("converts <a href> to a markdown link", () => {
+    expect(stripHtmlToText('<a href="https://example.com">click</a>')).toBe(
+      "[click](https://example.com)",
+    );
+  });
+
+  it("decodes common HTML entities", () => {
+    expect(stripHtmlToText("Tom &amp; Jerry &lt;3")).toBe("Tom & Jerry <3");
+  });
+
+  it("collapses block tags into newlines and removes the rest", () => {
+    const html = "<p>One.</p><p>Two.</p>";
+    expect(stripHtmlToText(html).trim()).toBe("One.\nTwo.");
+  });
+});