@affanhamid/markdown-renderer 2.1.0 → 2.3.0

package/README.md

@@ -1,16 +1,16 @@
 # @affanhamid/markdown-renderer
 
-A React markdown renderer built for AI-generated content. Handles the math rendering problems that react-markdown + remark-math can't.
+> A React markdown renderer built for AI-generated content. One import. Math, code, diagrams, callouts — all handled.
 
-## Why this exists
+## The Problem
 
 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.
+| Problem | Details |
+|---------|---------|
+| **Dollar signs break everything** | `remark-math` uses `$` for math, but `$` is also currency. Their `singleDollarTextMath: false` disables single-dollar math entirely. This package disambiguates intelligently: `$20` → currency, `$x + y$` → math. |
+| **Inconsistent math delimiters** | GPT, Claude, and Gemini variously output `$`, `$$`, `\(…\)`, and `\[…\]`. `remark-math` doesn't support `\(…\)` or `\[…\]`. This package normalizes all four formats automatically. |
+| **Too many moving parts** | The standard setup: `react-markdown` + `remark-math` + `remark-gfm` + `rehype-katex` + KaTeX CSS + syntax highlighter + custom components. This package is **one import**. |
 
 ## Features
 
@@ -21,6 +21,8 @@ If you've used `react-markdown` with `remark-math` and `rehype-katex` to render
 - **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)
+- **Callout blocks** — LaTeX-style `\begin{callout}{color}...\end{callout}` with any Tailwind color name
+- **Mermaid diagrams** — fenced `mermaid` code blocks render as diagrams (client-side hydration with dynamic import)
 - **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
 
@@ -98,6 +100,36 @@ import { MATH_MARKDOWN_RULES_APPENDIX } from "@affanhamid/markdown-renderer";
 const systemPrompt = `You are a helpful assistant.\n\n${MATH_MARKDOWN_RULES_APPENDIX}`;
 ```
 
+### Callout blocks
+
+Use LaTeX-style syntax with any Tailwind color name:
+
+```md
+\begin{callout}{amber}
+**Warning:** This operation is irreversible.
+\end{callout}
+
+\begin{callout}{green}
+**Tip:** Use `Ctrl+S` to save quickly.
+\end{callout}
+```
+
+Renders as styled callout boxes with `border-{color}-200`, `bg-{color}-50`, and `text-{color}-900` classes.
+
+### Mermaid diagrams
+
+Fenced code blocks with `mermaid` as the language render as diagrams:
+
+````md
+```mermaid
+graph LR
+  A[Input] --> B[Process]
+  B --> C[Output]
+```
+````
+
+On the client, mermaid is dynamically imported and renders after hydration. For server-side rendering (`renderMarkdownToHtml`), a `<pre>` fallback is output inside a `.md-mermaid` container with `data-mermaid-code` for later hydration.
+
 ## API
 
 ### `<MarkdownRenderer />` (default export)
@@ -105,6 +137,7 @@ const systemPrompt = `You are a helpful assistant.\n\n${MATH_MARKDOWN_RULES_APPE
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `markdown` | `string` | required | Markdown content to render |
+| `className` | `string` | `undefined` | CSS class applied to the wrapper `<div>` |
 | `onRunCode` | `(code: string, language: string) => Promise<CodeExecutionResult>` | `undefined` | Callback for executing code blocks |
 | `executableLanguages` | `string[]` | `["python", "r"]` | Languages that get a "Run" button |
 
@@ -130,6 +163,100 @@ Normalizes `\(...\)` to `$...$` and `\[...\]` to `$$...$$`. Converts inline `$$.
 
 A plain-text string with math formatting rules to append to LLM system prompts.
 
+## Theming with Tailwind CSS
+
+The `className` prop sets a class on the outer wrapper `<div>`, which you can use as a scoping selector for custom themes.
+
+```tsx
+<MarkdownRenderer markdown={content} className="my-theme" />
+```
+
+This renders:
+
+```html
+<div class="my-theme">
+  <h1>...</h1>
+  <p>...</p>
+  <div class="md-callout ...">...</div>
+  <!-- etc. -->
+</div>
+```
+
+### Creating a theme file
+
+Create a CSS file (e.g. `markdown-theme.css`) that uses descendant selectors scoped to your theme class. With Tailwind, use `@apply` for utility-based styling:
+
+```css
+/* markdown-theme.css */
+
+.my-theme h1 {
+  @apply text-3xl font-bold mt-8 mb-4 text-gray-900;
+}
+
+.my-theme h2 {
+  @apply text-2xl font-semibold mt-6 mb-3 text-gray-800;
+}
+
+.my-theme p {
+  @apply text-base leading-7 mb-4 text-gray-700;
+}
+
+.my-theme code {
+  @apply bg-gray-100 text-sm px-1.5 py-0.5 rounded font-mono;
+}
+
+.my-theme pre {
+  @apply rounded-lg my-4 overflow-x-auto;
+}
+
+.my-theme .md-callout {
+  @apply border-l-4 border-blue-400 bg-blue-50 px-4 py-3 my-4 rounded-r-lg;
+}
+
+.my-theme table {
+  @apply w-full border-collapse my-4 text-sm;
+}
+
+.my-theme th {
+  @apply bg-gray-50 font-semibold text-left px-3 py-2 border border-gray-200;
+}
+
+.my-theme td {
+  @apply px-3 py-2 border border-gray-200;
+}
+```
+
+Import the theme file in your app and pass the matching class name:
+
+```tsx
+import "./markdown-theme.css";
+
+<MarkdownRenderer markdown={content} className="my-theme" />
+```
+
+### Semantic CSS classes
+
+The renderer outputs these classes that you can target in your theme:
+
+| Class | Element |
+|-------|---------|
+| `md-callout` | Callout/admonition blocks (`> [!NOTE]`, etc.) |
+| `md-code-block` | Executable code block wrapper |
+| `md-code-block-header` | Header bar above executable code blocks |
+| `md-code-output` | Code execution output area |
+| `md-code-error` | Code execution error output |
+| `md-mermaid` | Mermaid diagram container |
+| `md-run-btn` | "Run" button on executable code blocks |
+
+### Works with server-side rendering
+
+`renderMarkdownToHtml()` produces the same HTML structure (wrapped in `<div class="prose max-w-none">`), so the same theme CSS applies to both client and server-rendered output. For server rendering, scope your selectors to the `prose` class or add a wrapper with your theme class:
+
+```ts
+const html = renderMarkdownToHtml(content);
+const themed = `<div class="my-theme">${html}</div>`;
+```
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -922,6 +922,7 @@ function renderMarkdownToHtml(markdown, options) {
 }
 var MarkdownRenderer = ({
   markdown,
+  className,
   onRunCode,
   executableLanguages = ["python", "r"]
 }) => {
@@ -1103,7 +1104,7 @@ var MarkdownRenderer = ({
       alive = false;
     };
   }, [html]);
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { ref: containerRef, dangerouslySetInnerHTML: { __html: html } });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { ref: containerRef, className, dangerouslySetInnerHTML: { __html: html } });
 };
 var markdown_renderer_default = MarkdownRenderer;
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.d.cts

@@ -7,13 +7,14 @@ interface CodeExecutionResult {
 }
 interface MarkdownRendererProps {
     markdown: string;
+    className?: string;
     onRunCode?: (code: string, language: string) => Promise<CodeExecutionResult>;
     executableLanguages?: string[];
 }
 declare function renderMarkdownToHtml(markdown: string, options?: {
     executableLanguages?: string[];
 }): string;
-declare const MarkdownRenderer: ({ markdown, onRunCode, executableLanguages, }: MarkdownRendererProps) => react_jsx_runtime.JSX.Element;
+declare const MarkdownRenderer: ({ markdown, className, onRunCode, executableLanguages, }: MarkdownRendererProps) => react_jsx_runtime.JSX.Element;
 
 declare function normalizeMathMarkdownDelimiters(markdown: string): string;
 declare const MATH_MARKDOWN_RULES_APPENDIX = "Math formatting rules (must follow):\n- Inline math: use single-dollar delimiters like $...$.\n- Display math: use $$ delimiters on their own lines with nothing else on those lines.\n- Do not use \\(...\\) or \\[...\\] delimiters.\n- Do not place display-math $$...$$ inside bullets or table cells; use inline $...$ there.\n- Escape non-math currency dollars as \\$.";

package/dist/index.d.ts

@@ -7,13 +7,14 @@ interface CodeExecutionResult {
 }
 interface MarkdownRendererProps {
     markdown: string;
+    className?: string;
     onRunCode?: (code: string, language: string) => Promise<CodeExecutionResult>;
     executableLanguages?: string[];
 }
 declare function renderMarkdownToHtml(markdown: string, options?: {
     executableLanguages?: string[];
 }): string;
-declare const MarkdownRenderer: ({ markdown, onRunCode, executableLanguages, }: MarkdownRendererProps) => react_jsx_runtime.JSX.Element;
+declare const MarkdownRenderer: ({ markdown, className, onRunCode, executableLanguages, }: MarkdownRendererProps) => react_jsx_runtime.JSX.Element;
 
 declare function normalizeMathMarkdownDelimiters(markdown: string): string;
 declare const MATH_MARKDOWN_RULES_APPENDIX = "Math formatting rules (must follow):\n- Inline math: use single-dollar delimiters like $...$.\n- Display math: use $$ delimiters on their own lines with nothing else on those lines.\n- Do not use \\(...\\) or \\[...\\] delimiters.\n- Do not place display-math $$...$$ inside bullets or table cells; use inline $...$ there.\n- Escape non-math currency dollars as \\$.";

package/dist/index.js

@@ -883,6 +883,7 @@ function renderMarkdownToHtml(markdown, options) {
 }
 var MarkdownRenderer = ({
   markdown,
+  className,
   onRunCode,
   executableLanguages = ["python", "r"]
 }) => {
@@ -1064,7 +1065,7 @@ var MarkdownRenderer = ({
       alive = false;
     };
   }, [html]);
-  return /* @__PURE__ */ jsx("div", { ref: containerRef, dangerouslySetInnerHTML: { __html: html } });
+  return /* @__PURE__ */ jsx("div", { ref: containerRef, className, dangerouslySetInnerHTML: { __html: html } });
 };
 var markdown_renderer_default = MarkdownRenderer;
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@affanhamid/markdown-renderer",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Custom markdown renderer with KaTeX support",
   "type": "module",
   "main": "dist/index.cjs",