@affanhamid/markdown-renderer 2.0.0 → 2.1.0

package/README.md

@@ -0,0 +1,135 @@
+# @affanhamid/markdown-renderer
+
+A React markdown renderer built for AI-generated content. Handles the math rendering problems that react-markdown + remark-math can't.
+
+## Why this exists
+
+If you've used `react-markdown` with `remark-math` and `rehype-katex` to render LLM output, you've hit these problems:
+
+**1. Dollar signs break everything.** `remark-math` uses `$` for LaTeX math, but `$` is also currency. Their `singleDollarTextMath: false` option disables single-dollar math entirely, forcing `$$` for everything. This package disambiguates intelligently: `$20` renders as currency (digit follows `$`), while `$x + y$` renders as math. It also handles CJK characters, Devanagari/Hindi punctuation, and fullwidth punctuation as valid math boundaries.
+
+**2. AI models use inconsistent math delimiters.** GPT, Claude, and Gemini variously output `$...$`, `$$...$$`, `\(...\)`, and `\[...\]`. `remark-math` does not support `\(...\)` or `\[...\]` — there's an [open discussion](https://github.com/remarkjs/remark-math/issues) with no resolution. This package normalizes all four formats automatically before rendering.
+
+**3. Too many moving parts.** The standard setup requires `react-markdown` + `remark-math` + `remark-gfm` + `rehype-katex` + KaTeX CSS + a syntax highlighter + custom components for tables, images, code blocks. This package is one import.
+
+## Features
+
+- **Math rendering** — KaTeX with automatic delimiter normalization (`$`, `$$`, `\(`, `\[`)
+- **Dollar sign disambiguation** — currency vs. math, with CJK/Devanagari/fullwidth support
+- **Syntax highlighting** — Shiki with `github-light` theme and copy-to-clipboard
+- **Tables** — GFM-style with column alignment (left, center, right)
+- **Executable code blocks** — optional `onRunCode` callback for running Python, R, etc.
+- **Inline images** — `![alt](url)` works inside paragraphs, not just as standalone blocks
+- **Semantic color tags** — `{color:important}text{/color}` for highlighting (important, definition, example, note, formula)
+- **Auto-scaling brackets** — `($x + y$)` automatically uses `\left(` and `\right)` for proper sizing
+- **Prompt appendix** — exported `MATH_MARKDOWN_RULES_APPENDIX` string to append to your LLM system prompt, steering models toward consistent delimiter usage
+
+## Installation
+
+```bash
+npm install @affanhamid/markdown-renderer
+```
+
+Peer dependency: `react >= 18`
+
+## Usage
+
+### React component
+
+```tsx
+import { MarkdownRenderer } from "@affanhamid/markdown-renderer";
+
+function ChatMessage({ content }: { content: string }) {
+  return <MarkdownRenderer markdown={content} />;
+}
+```
+
+### With executable code blocks
+
+```tsx
+import { MarkdownRenderer } from "@affanhamid/markdown-renderer";
+
+function Notebook({ content }: { content: string }) {
+  const handleRunCode = async (code: string, language: string) => {
+    const result = await executeOnServer(code, language);
+    return {
+      output: result.stdout,
+      error: result.stderr,
+      images: result.plots, // base64 data URIs
+    };
+  };
+
+  return (
+    <MarkdownRenderer
+      markdown={content}
+      onRunCode={handleRunCode}
+      executableLanguages={["python", "r"]}
+    />
+  );
+}
+```
+
+### Server-side HTML (no React)
+
+```ts
+import { renderMarkdownToHtml } from "@affanhamid/markdown-renderer";
+
+const html = renderMarkdownToHtml(markdownString);
+```
+
+### Normalize delimiters only
+
+If you want to preprocess markdown before passing it to your own renderer:
+
+```ts
+import { normalizeMathMarkdownDelimiters } from "@affanhamid/markdown-renderer";
+
+// Converts \(...\) -> $...$, \[...\] -> $$...$$, inline $$...$$ -> $...$
+const normalized = normalizeMathMarkdownDelimiters(rawMarkdown);
+```
+
+### Prompt engineering helper
+
+Append this to your LLM system prompt to reduce delimiter inconsistency at the source:
+
+```ts
+import { MATH_MARKDOWN_RULES_APPENDIX } from "@affanhamid/markdown-renderer";
+
+const systemPrompt = `You are a helpful assistant.\n\n${MATH_MARKDOWN_RULES_APPENDIX}`;
+```
+
+## API
+
+### `<MarkdownRenderer />` (default export)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `markdown` | `string` | required | Markdown content to render |
+| `onRunCode` | `(code: string, language: string) => Promise<CodeExecutionResult>` | `undefined` | Callback for executing code blocks |
+| `executableLanguages` | `string[]` | `["python", "r"]` | Languages that get a "Run" button |
+
+### `CodeExecutionResult`
+
+```ts
+interface CodeExecutionResult {
+  output: string;
+  error?: string;
+  images?: string[]; // data URIs or URLs
+}
+```
+
+### `renderMarkdownToHtml(markdown: string, options?: { executableLanguages?: string[] }): string`
+
+Renders markdown to an HTML string. Works without React (server-side, emails, PDFs).
+
+### `normalizeMathMarkdownDelimiters(markdown: string): string`
+
+Normalizes `\(...\)` to `$...$` and `\[...\]` to `$$...$$`. Converts inline `$$...$$` to `$...$`. Leaves code fences untouched.
+
+### `MATH_MARKDOWN_RULES_APPENDIX: string`
+
+A plain-text string with math formatting rules to append to LLM system prompts.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -820,6 +820,13 @@ function renderMarkdownToHtml(markdown, options) {
           const isExecutable = options?.executableLanguages && language && options.executableLanguages.includes(language.toLowerCase());
           const currentIndex = codeBlockIndex;
           codeBlockIndex++;
+          if (language === "mermaid") {
+            parts.push(
+              `<div class="md-mermaid" data-mermaid-code="${escapeHtml(codeContent)}"><pre style="overflow-x:auto;background:#f7f7f7;padding:0.75rem;border-radius:0.375rem;font-size:0.8rem;color:#666"><code>${escapedCode}</code></pre></div>`
+            );
+            i++;
+            break;
+          }
           if (isExecutable) {
             parts.push(
               `<div class="md-code-block" data-language="${escapedLang}" data-code-index="${currentIndex}" data-executable="true"><div class="md-code-block-header" style="display:flex;align-items:center;justify-content:space-between;padding:0.25rem 0.75rem;background:#f0f0f0;border-radius:0.375rem 0.375rem 0 0;border:1px solid #e0e0e0;border-bottom:none"><span style="font-size:0.75rem;color:#666;font-family:monospace">${escapedLang}</span><button class="md-run-btn" data-code-index="${currentIndex}" style="padding:0.2rem 0.6rem;font-size:0.75rem;border-radius:0.25rem;border:1px solid #ccc;background:#fff;cursor:pointer;font-family:inherit">Run</button></div><pre style="overflow-x:auto;border-radius:0 0 0.375rem 0.375rem;background:#f7f7f7;color:#1f2937;padding:0.75rem;font-size:0.875rem;margin:0;border:1px solid #e0e0e0;border-top:none"><code class="language-${escapedLang}" data-executable="true">${escapedCode}</code></pre><div class="md-code-output" data-output-for="${currentIndex}" style="display:none"></div></div>`
@@ -847,6 +854,28 @@ function renderMarkdownToHtml(markdown, options) {
       i++;
       continue;
     }
+    const calloutMatch = trimmed.match(/^\\begin\{callout\}\{(\w+)\}$/);
+    if (calloutMatch && calloutMatch[1]) {
+      const color = calloutMatch[1];
+      const contentLines = [];
+      i++;
+      while (i < lines.length) {
+        const calloutLine = (lines[i] || "").trim();
+        if (calloutLine === "\\end{callout}") {
+          i++;
+          break;
+        }
+        contentLines.push(lines[i] || "");
+        i++;
+      }
+      const innerHtml = renderMarkdownToHtml(contentLines.join("\n"), options);
+      const innerMatch = innerHtml.match(/<div class="prose[^"]*">(.*)<\/div>/s);
+      const innerContent = innerMatch?.[1] ?? escapeHtml(contentLines.join("\n"));
+      parts.push(
+        `<div class="md-callout border-${color}-200 bg-${color}-50 text-${color}-900 dark:border-${color}-700/40 dark:bg-${color}-900/10 dark:text-${color}-200 my-4 rounded-lg border px-4 py-3 text-sm leading-relaxed [&>p]:mb-0 [&>p:last-child]:mb-0">${innerContent}</div>`
+      );
+      continue;
+    }
     const imageMatch = trimmed.match(/^!\[([^\]]*)\]\(([^)]+)\)$/);
     if (imageMatch && imageMatch[2]) {
       const alt = escapeHtml(imageMatch[1] ?? "");
@@ -1038,6 +1067,42 @@ var MarkdownRenderer = ({
       );
     };
   }, [html, handleRun]);
+  (0, import_react.useEffect)(() => {
+    const container = containerRef.current;
+    if (!container) return;
+    const mermaidBlocks = container.querySelectorAll(".md-mermaid");
+    if (mermaidBlocks.length === 0) return;
+    let alive = true;
+    void (async () => {
+      try {
+        const mermaid = (await import("mermaid")).default;
+        mermaid.initialize({
+          startOnLoad: false,
+          securityLevel: "antiscript",
+          theme: "neutral",
+          fontFamily: "ui-sans-serif, system-ui, sans-serif",
+          fontSize: 13,
+          htmlLabels: false,
+          flowchart: { useMaxWidth: true, htmlLabels: false },
+          sequence: { useMaxWidth: true }
+        });
+        for (const block of Array.from(mermaidBlocks)) {
+          if (!alive) break;
+          const code = block.getAttribute("data-mermaid-code") || "";
+          const id = `mermaid-${Math.random().toString(36).slice(2, 9)}`;
+          try {
+            const { svg } = await mermaid.render(id, code.trim());
+            block.innerHTML = `<div style="display:flex;justify-content:center;overflow:auto;padding:1rem">${svg}</div>`;
+          } catch {
+          }
+        }
+      } catch {
+      }
+    })();
+    return () => {
+      alive = false;
+    };
+  }, [html]);
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { ref: containerRef, dangerouslySetInnerHTML: { __html: html } });
 };
 var markdown_renderer_default = MarkdownRenderer;

package/dist/index.js

@@ -781,6 +781,13 @@ function renderMarkdownToHtml(markdown, options) {
           const isExecutable = options?.executableLanguages && language && options.executableLanguages.includes(language.toLowerCase());
           const currentIndex = codeBlockIndex;
           codeBlockIndex++;
+          if (language === "mermaid") {
+            parts.push(
+              `<div class="md-mermaid" data-mermaid-code="${escapeHtml(codeContent)}"><pre style="overflow-x:auto;background:#f7f7f7;padding:0.75rem;border-radius:0.375rem;font-size:0.8rem;color:#666"><code>${escapedCode}</code></pre></div>`
+            );
+            i++;
+            break;
+          }
           if (isExecutable) {
             parts.push(
               `<div class="md-code-block" data-language="${escapedLang}" data-code-index="${currentIndex}" data-executable="true"><div class="md-code-block-header" style="display:flex;align-items:center;justify-content:space-between;padding:0.25rem 0.75rem;background:#f0f0f0;border-radius:0.375rem 0.375rem 0 0;border:1px solid #e0e0e0;border-bottom:none"><span style="font-size:0.75rem;color:#666;font-family:monospace">${escapedLang}</span><button class="md-run-btn" data-code-index="${currentIndex}" style="padding:0.2rem 0.6rem;font-size:0.75rem;border-radius:0.25rem;border:1px solid #ccc;background:#fff;cursor:pointer;font-family:inherit">Run</button></div><pre style="overflow-x:auto;border-radius:0 0 0.375rem 0.375rem;background:#f7f7f7;color:#1f2937;padding:0.75rem;font-size:0.875rem;margin:0;border:1px solid #e0e0e0;border-top:none"><code class="language-${escapedLang}" data-executable="true">${escapedCode}</code></pre><div class="md-code-output" data-output-for="${currentIndex}" style="display:none"></div></div>`
@@ -808,6 +815,28 @@ function renderMarkdownToHtml(markdown, options) {
       i++;
       continue;
     }
+    const calloutMatch = trimmed.match(/^\\begin\{callout\}\{(\w+)\}$/);
+    if (calloutMatch && calloutMatch[1]) {
+      const color = calloutMatch[1];
+      const contentLines = [];
+      i++;
+      while (i < lines.length) {
+        const calloutLine = (lines[i] || "").trim();
+        if (calloutLine === "\\end{callout}") {
+          i++;
+          break;
+        }
+        contentLines.push(lines[i] || "");
+        i++;
+      }
+      const innerHtml = renderMarkdownToHtml(contentLines.join("\n"), options);
+      const innerMatch = innerHtml.match(/<div class="prose[^"]*">(.*)<\/div>/s);
+      const innerContent = innerMatch?.[1] ?? escapeHtml(contentLines.join("\n"));
+      parts.push(
+        `<div class="md-callout border-${color}-200 bg-${color}-50 text-${color}-900 dark:border-${color}-700/40 dark:bg-${color}-900/10 dark:text-${color}-200 my-4 rounded-lg border px-4 py-3 text-sm leading-relaxed [&>p]:mb-0 [&>p:last-child]:mb-0">${innerContent}</div>`
+      );
+      continue;
+    }
     const imageMatch = trimmed.match(/^!\[([^\]]*)\]\(([^)]+)\)$/);
     if (imageMatch && imageMatch[2]) {
       const alt = escapeHtml(imageMatch[1] ?? "");
@@ -999,6 +1028,42 @@ var MarkdownRenderer = ({
       );
     };
   }, [html, handleRun]);
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+    const mermaidBlocks = container.querySelectorAll(".md-mermaid");
+    if (mermaidBlocks.length === 0) return;
+    let alive = true;
+    void (async () => {
+      try {
+        const mermaid = (await import("mermaid")).default;
+        mermaid.initialize({
+          startOnLoad: false,
+          securityLevel: "antiscript",
+          theme: "neutral",
+          fontFamily: "ui-sans-serif, system-ui, sans-serif",
+          fontSize: 13,
+          htmlLabels: false,
+          flowchart: { useMaxWidth: true, htmlLabels: false },
+          sequence: { useMaxWidth: true }
+        });
+        for (const block of Array.from(mermaidBlocks)) {
+          if (!alive) break;
+          const code = block.getAttribute("data-mermaid-code") || "";
+          const id = `mermaid-${Math.random().toString(36).slice(2, 9)}`;
+          try {
+            const { svg } = await mermaid.render(id, code.trim());
+            block.innerHTML = `<div style="display:flex;justify-content:center;overflow:auto;padding:1rem">${svg}</div>`;
+          } catch {
+          }
+        }
+      } catch {
+      }
+    })();
+    return () => {
+      alive = false;
+    };
+  }, [html]);
   return /* @__PURE__ */ jsx("div", { ref: containerRef, dangerouslySetInnerHTML: { __html: html } });
 };
 var markdown_renderer_default = MarkdownRenderer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@affanhamid/markdown-renderer",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Custom markdown renderer with KaTeX support",
   "type": "module",
   "main": "dist/index.cjs",
@@ -14,7 +14,7 @@
     }
   },
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --external react",
+    "build": "tsup src/index.ts --format cjs,esm --dts --external react --external mermaid",
     "test": "jest"
   },
   "dependencies": {
@@ -22,19 +22,27 @@
     "shiki": "^4.0.1"
   },
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "mermaid": ">=10"
+  },
+  "peerDependenciesMeta": {
+    "mermaid": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
     "@types/katex": "^0.16.7",
     "@types/react": "^19.0.0",
     "jest": "^30.2.0",
+    "mermaid": "^11.12.3",
     "ts-jest": "^29.4.6",
     "tsup": "^8.0.0",
     "typescript": "^5.8.0"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "license": "MIT"
 }