@changerawr/markdown 1.1.11 → 1.2.0

package/README.md

@@ -255,23 +255,20 @@ The main component for rendering markdown:
 
 ## 🔧 Custom Extensions
 
-Create powerful custom extensions to extend markdown syntax:
+Extensions are the building block of the entire library — every feature, including all the built-ins, is an extension. You can add new syntax, replace existing behaviour, or attach full React components for framework-specific rendering while keeping a plain-HTML fallback for everywhere else.
 
 ```typescript
-import { ChangerawrMarkdown } from '@changerawr/markdown';
-
-const engine = new ChangerawrMarkdown();
+import { createEngine } from '@changerawr/markdown';
 
-// Add a highlight extension
-const highlightExtension = {
+const HighlightExtension = {
   name: 'highlight',
   parseRules: [{
     name: 'highlight',
-    pattern: /==(.+?)==/g,
+    pattern: /==(.+?)==/,
     render: (match) => ({
       type: 'highlight',
-      content: match[1],
-      raw: match[0]
+      content: match[1] ?? '',
+      raw: match[0] ?? '',
     })
   }],
   renderRules: [{
@@ -280,12 +277,17 @@ const highlightExtension = {
   }]
 };
 
-engine.registerExtension(highlightExtension);
+const engine = createEngine();
+engine.registerExtension(HighlightExtension);
 
-const html = engine.toHtml('This is ==highlighted text==');
-// <mark class="bg-yellow-200 px-1">highlighted text</mark>
+engine.toHtml('This is ==highlighted text==');
+// Works in React, Astro, vanilla JS, Node — everywhere.
 ```
 
+**[Full extension documentation →](./EXTENSIONS.md)**
+
+The guide covers: block extensions, inline extensions, passing attributes, component extensions with React state and lifecycle, Astro compatibility, priority ordering, TypeScript types, and a complete worked example.
+
 ## 🎯 Advanced Configuration
 
 ### Engine Configuration
@@ -632,6 +634,7 @@ npm run test:coverage   # Run with coverage report
 ### React Hooks
 
 - `useMarkdown(content: string, options?)` - Main markdown processing hook
+- `useMarkdownComponents(content: string, options?)` - Hook for component extensions (returns `componentMap` + `renderBatch`)
 - `useMarkdownEngine(options?)` - Engine management hook
 - `useMarkdownDebug(content: string)` - Debug information hook
 
@@ -645,7 +648,13 @@ npm run test:coverage   # Run with coverage report
 
 - **Core Extensions**: `CoreExtensions` array or individual exports
 - **Feature Extensions**: `AlertExtension`, `ButtonExtension`, `EmbedExtension`
-- **Custom**: Create your own with `parseRules` and `renderRules`
+- **Custom**: Create your own with `parseRules` and `renderRules` — [see the extension guide](./EXTENSIONS.md)
+- **Component Extensions**: Attach React components to render rules via `ReactComponentExtension` (with universal string fallback for Astro, HTML, etc.)
+
+### Astro
+
+- `renderMarkdownForAstro(content, options?)` — server-side render to HTML string
+- `<MarkdownRenderer />` — zero-JS Astro component (`@changerawr/markdown/astro/MarkdownRenderer.astro`)
 
 ## 🤝 Contributing
 

package/dist/astro/MarkdownRenderer.astro

@@ -0,0 +1,31 @@
+---
+/**
+ * @changerawr/markdown — Astro MarkdownRenderer component
+ *
+ * Usage:
+ *   import MarkdownRenderer from '@changerawr/markdown/astro/MarkdownRenderer.astro';
+ *
+ *   <MarkdownRenderer content={post.body} format="tailwind" class="prose" />
+ *
+ * The component renders markdown server-side at build / SSR time — zero client JS.
+ */
+import { renderMarkdownForAstro } from '@changerawr/markdown/astro';
+import type { AstroMarkdownRendererProps } from '@changerawr/markdown/astro';
+
+type Props = AstroMarkdownRendererProps;
+
+const {
+    content,
+    format = 'html',
+    class: className,
+    config,
+    extensions,
+} = Astro.props;
+
+const html = renderMarkdownForAstro(content, { format, config, extensions });
+---
+
+<div
+    class:list={['changerawr-markdown', className]}
+    set:html={html}
+/>

package/dist/astro/index.d.mts

@@ -0,0 +1,213 @@
+interface MarkdownToken {
+    type: string;
+    content: string;
+    raw: string;
+    attributes?: Record<string, string | number | boolean | Function | any>;
+    children?: MarkdownToken[];
+}
+interface ParseRule {
+    name: string;
+    pattern: RegExp;
+    render: (match: RegExpMatchArray) => MarkdownToken;
+}
+interface RenderRule {
+    type: string;
+    render: (token: MarkdownToken) => string;
+}
+interface Extension {
+    name: string;
+    parseRules: ParseRule[];
+    renderRules: RenderRule[];
+}
+type OutputFormat = 'html' | 'tailwind' | 'json';
+interface RendererConfig {
+    format: OutputFormat;
+    sanitize?: boolean;
+    allowUnsafeHtml?: boolean;
+    customClasses?: Record<string, string>;
+    debugMode?: boolean;
+}
+interface ParserConfig {
+    debugMode?: boolean;
+    maxIterations?: number;
+    validateMarkdown?: boolean;
+}
+interface EngineConfig {
+    parser?: ParserConfig;
+    renderer?: RendererConfig;
+    extensions?: Extension[];
+}
+interface DebugInfo {
+    warnings: string[];
+    parseTime: number;
+    renderTime: number;
+    tokenCount: number;
+    iterationCount: number;
+}
+interface PerformanceMetrics {
+    parseTime: number;
+    renderTime: number;
+    totalTime: number;
+    tokenCount: number;
+    memoryUsed?: number;
+}
+interface ExtensionRegistration {
+    success: boolean;
+    extensionName: string;
+    error?: string;
+    conflictingRules?: string[];
+}
+
+/**
+ * Props for the Astro MarkdownRenderer component.
+ */
+interface AstroMarkdownRendererProps {
+    /** Markdown content to render */
+    content: string;
+    /** Output format — 'html' (default) or 'tailwind' */
+    format?: 'html' | 'tailwind';
+    /** CSS class(es) to add to the wrapper element */
+    class?: string;
+    /** Engine configuration */
+    config?: EngineConfig;
+    /** Additional extensions to register */
+    extensions?: Extension[];
+}
+
+/**
+ * Plain HTML output renderer - no CSS framework classes
+ */
+
+/**
+ * Render markdown to plain HTML without CSS framework classes
+ */
+declare function renderToHTML(markdown: string, config?: Omit<EngineConfig, 'renderer'>): string;
+/**
+ * Parse markdown and render to HTML with custom configuration
+ */
+declare function renderToHTMLWithConfig(markdown: string, rendererConfig: {
+    sanitize?: boolean;
+    allowUnsafeHtml?: boolean;
+    debugMode?: boolean;
+}): string;
+
+/**
+ * Tailwind CSS output renderer - HTML with Tailwind CSS classes
+ */
+
+/**
+ * Render markdown to HTML with Tailwind CSS classes (default behavior)
+ */
+declare function renderToTailwind(markdown: string, config?: Omit<EngineConfig, 'renderer'>): string;
+/**
+ * Render markdown to Tailwind HTML with custom configuration
+ */
+declare function renderToTailwindWithConfig(markdown: string, rendererConfig: {
+    sanitize?: boolean;
+    allowUnsafeHtml?: boolean;
+    customClasses?: Record<string, string>;
+    debugMode?: boolean;
+}): string;
+
+interface CacheStats {
+    size: number;
+    capacity: number;
+    hits: number;
+    misses: number;
+    hitRate: number;
+    evictions: number;
+}
+
+interface RenderMetrics {
+    inputSize: number;
+    parseTime: number;
+    renderTime: number;
+    totalTime: number;
+    tokenCount: number;
+    cacheHit: boolean;
+}
+declare class ChangerawrMarkdown {
+    private parser;
+    private renderer;
+    private extensions;
+    private parseCache;
+    private renderCache;
+    private parseTime;
+    private renderTime;
+    private lastTokenCount;
+    constructor(config?: EngineConfig);
+    private registerFeatureExtensions;
+    private registerCoreExtensions;
+    registerExtension(extension: Extension): ExtensionRegistration;
+    unregisterExtension(name: string): boolean;
+    parse(markdown: string): MarkdownToken[];
+    render(tokens: MarkdownToken[], cacheKey?: string): string;
+    toHtml(markdown: string): string;
+    /**
+     * Render markdown with performance metrics
+     */
+    toHtmlWithMetrics(markdown: string): {
+        html: string;
+        metrics: RenderMetrics;
+    };
+    /**
+     * Stream-render large documents in chunks for better performance
+     */
+    toHtmlStreamed(markdown: string, options?: {
+        chunkSize?: number;
+        onChunk?: (chunk: {
+            html: string;
+            progress: number;
+        }) => void;
+    }): Promise<string>;
+    getExtensions(): string[];
+    hasExtension(name: string): boolean;
+    getWarnings(): string[];
+    getDebugInfo(): DebugInfo | null;
+    getPerformanceMetrics(): PerformanceMetrics | null;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        parse: CacheStats;
+        render: CacheStats;
+    };
+    /**
+     * Clear all caches
+     */
+    clearCaches(): void;
+    /**
+     * Update cache capacity
+     */
+    setCacheSize(size: number): void;
+    private rebuildParserAndRenderer;
+}
+
+/**
+ * @changerawr/markdown — Astro integration utilities
+ *
+ * Usage:
+ *   import { renderMarkdownForAstro } from '@changerawr/markdown/astro';
+ *
+ * For the Astro component:
+ *   import MarkdownRenderer from '@changerawr/markdown/astro/MarkdownRenderer.astro';
+ */
+
+/**
+ * Render markdown to an HTML string suitable for Astro's `set:html` directive.
+ * Runs entirely server-side — no client JavaScript emitted.
+ *
+ * @example
+ * ---
+ * import { renderMarkdownForAstro } from '@changerawr/markdown/astro';
+ * const html = renderMarkdownForAstro(Astro.props.content);
+ * ---
+ * <div set:html={html} />
+ */
+declare function renderMarkdownForAstro(content: string, options?: {
+    format?: 'html' | 'tailwind';
+    config?: EngineConfig;
+    extensions?: Extension[];
+}): string;
+
+export { type AstroMarkdownRendererProps, ChangerawrMarkdown, type EngineConfig, type Extension, type MarkdownToken, renderMarkdownForAstro, renderToHTML, renderToHTMLWithConfig, renderToTailwind, renderToTailwindWithConfig };

package/dist/astro/index.d.ts

@@ -0,0 +1,213 @@
+interface MarkdownToken {
+    type: string;
+    content: string;
+    raw: string;
+    attributes?: Record<string, string | number | boolean | Function | any>;
+    children?: MarkdownToken[];
+}
+interface ParseRule {
+    name: string;
+    pattern: RegExp;
+    render: (match: RegExpMatchArray) => MarkdownToken;
+}
+interface RenderRule {
+    type: string;
+    render: (token: MarkdownToken) => string;
+}
+interface Extension {
+    name: string;
+    parseRules: ParseRule[];
+    renderRules: RenderRule[];
+}
+type OutputFormat = 'html' | 'tailwind' | 'json';
+interface RendererConfig {
+    format: OutputFormat;
+    sanitize?: boolean;
+    allowUnsafeHtml?: boolean;
+    customClasses?: Record<string, string>;
+    debugMode?: boolean;
+}
+interface ParserConfig {
+    debugMode?: boolean;
+    maxIterations?: number;
+    validateMarkdown?: boolean;
+}
+interface EngineConfig {
+    parser?: ParserConfig;
+    renderer?: RendererConfig;
+    extensions?: Extension[];
+}
+interface DebugInfo {
+    warnings: string[];
+    parseTime: number;
+    renderTime: number;
+    tokenCount: number;
+    iterationCount: number;
+}
+interface PerformanceMetrics {
+    parseTime: number;
+    renderTime: number;
+    totalTime: number;
+    tokenCount: number;
+    memoryUsed?: number;
+}
+interface ExtensionRegistration {
+    success: boolean;
+    extensionName: string;
+    error?: string;
+    conflictingRules?: string[];
+}
+
+/**
+ * Props for the Astro MarkdownRenderer component.
+ */
+interface AstroMarkdownRendererProps {
+    /** Markdown content to render */
+    content: string;
+    /** Output format — 'html' (default) or 'tailwind' */
+    format?: 'html' | 'tailwind';
+    /** CSS class(es) to add to the wrapper element */
+    class?: string;
+    /** Engine configuration */
+    config?: EngineConfig;
+    /** Additional extensions to register */
+    extensions?: Extension[];
+}
+
+/**
+ * Plain HTML output renderer - no CSS framework classes
+ */
+
+/**
+ * Render markdown to plain HTML without CSS framework classes
+ */
+declare function renderToHTML(markdown: string, config?: Omit<EngineConfig, 'renderer'>): string;
+/**
+ * Parse markdown and render to HTML with custom configuration
+ */
+declare function renderToHTMLWithConfig(markdown: string, rendererConfig: {
+    sanitize?: boolean;
+    allowUnsafeHtml?: boolean;
+    debugMode?: boolean;
+}): string;
+
+/**
+ * Tailwind CSS output renderer - HTML with Tailwind CSS classes
+ */
+
+/**
+ * Render markdown to HTML with Tailwind CSS classes (default behavior)
+ */
+declare function renderToTailwind(markdown: string, config?: Omit<EngineConfig, 'renderer'>): string;
+/**
+ * Render markdown to Tailwind HTML with custom configuration
+ */
+declare function renderToTailwindWithConfig(markdown: string, rendererConfig: {
+    sanitize?: boolean;
+    allowUnsafeHtml?: boolean;
+    customClasses?: Record<string, string>;
+    debugMode?: boolean;
+}): string;
+
+interface CacheStats {
+    size: number;
+    capacity: number;
+    hits: number;
+    misses: number;
+    hitRate: number;
+    evictions: number;
+}
+
+interface RenderMetrics {
+    inputSize: number;
+    parseTime: number;
+    renderTime: number;
+    totalTime: number;
+    tokenCount: number;
+    cacheHit: boolean;
+}
+declare class ChangerawrMarkdown {
+    private parser;
+    private renderer;
+    private extensions;
+    private parseCache;
+    private renderCache;
+    private parseTime;
+    private renderTime;
+    private lastTokenCount;
+    constructor(config?: EngineConfig);
+    private registerFeatureExtensions;
+    private registerCoreExtensions;
+    registerExtension(extension: Extension): ExtensionRegistration;
+    unregisterExtension(name: string): boolean;
+    parse(markdown: string): MarkdownToken[];
+    render(tokens: MarkdownToken[], cacheKey?: string): string;
+    toHtml(markdown: string): string;
+    /**
+     * Render markdown with performance metrics
+     */
+    toHtmlWithMetrics(markdown: string): {
+        html: string;
+        metrics: RenderMetrics;
+    };
+    /**
+     * Stream-render large documents in chunks for better performance
+     */
+    toHtmlStreamed(markdown: string, options?: {
+        chunkSize?: number;
+        onChunk?: (chunk: {
+            html: string;
+            progress: number;
+        }) => void;
+    }): Promise<string>;
+    getExtensions(): string[];
+    hasExtension(name: string): boolean;
+    getWarnings(): string[];
+    getDebugInfo(): DebugInfo | null;
+    getPerformanceMetrics(): PerformanceMetrics | null;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        parse: CacheStats;
+        render: CacheStats;
+    };
+    /**
+     * Clear all caches
+     */
+    clearCaches(): void;
+    /**
+     * Update cache capacity
+     */
+    setCacheSize(size: number): void;
+    private rebuildParserAndRenderer;
+}
+
+/**
+ * @changerawr/markdown — Astro integration utilities
+ *
+ * Usage:
+ *   import { renderMarkdownForAstro } from '@changerawr/markdown/astro';
+ *
+ * For the Astro component:
+ *   import MarkdownRenderer from '@changerawr/markdown/astro/MarkdownRenderer.astro';
+ */
+
+/**
+ * Render markdown to an HTML string suitable for Astro's `set:html` directive.
+ * Runs entirely server-side — no client JavaScript emitted.
+ *
+ * @example
+ * ---
+ * import { renderMarkdownForAstro } from '@changerawr/markdown/astro';
+ * const html = renderMarkdownForAstro(Astro.props.content);
+ * ---
+ * <div set:html={html} />
+ */
+declare function renderMarkdownForAstro(content: string, options?: {
+    format?: 'html' | 'tailwind';
+    config?: EngineConfig;
+    extensions?: Extension[];
+}): string;
+
+export { type AstroMarkdownRendererProps, ChangerawrMarkdown, type EngineConfig, type Extension, type MarkdownToken, renderMarkdownForAstro, renderToHTML, renderToHTMLWithConfig, renderToTailwind, renderToTailwindWithConfig };