This is a paragraph.
\n with its attributes\n```\n\n**Default allowed tags:** `img`, `style`, `div`, `span`, `section`, `article`, `aside`, `header`, `footer`, `nav`, `main`, `figure`, `figcaption`, `details`, `summary`, `mark`, `time`, `video`, `audio`, `source`, `iframe`, `embed`\n\n**Script tags** are stripped by default for security. Opt-in with `allowedHTMLTags: ['script']`.\n\n### Slot Hooks (v2)\n\nResolve `[[SLOT_NAME]]` placeholders for personalization:\n\n```typescript\nconst pipeline = new MarkdownPipeline({\n onSlot: (name) => {\n const values = { USER_NAME: 'Alice', COMPANY: 'Acme' };\n return values[name] || `[[${name}]]`;\n }\n});\nconst html = pipeline.renderMarkdown('Hello [[USER_NAME]] from [[COMPANY]]!');\n// Output: Hello Alice from Acme!\n```\n\nCustom slot patterns are supported via `slotPattern`:\n\n```typescript\nconst pipeline = new MarkdownPipeline({\n slotPattern: /\\{\\{(.*?)\\}\\}/g,\n onSlot: (name) => values[name] || `{{${name}}}`\n});\n```\n\n### Error Recovery (v2)\n\nThree error recovery modes for production resilience:\n\n```typescript\n// 'throw' (default) — backward compatible, throws on parse errors\nconst strict = new MarkdownPipeline({ errorRecovery: 'throw' });\n\n// 'warn' — logs warning, returns partial content as fallback text\nconst tolerant = new MarkdownPipeline({ errorRecovery: 'warn' });\n\n// 'silent' — silently returns fallback content\nconst silent = new MarkdownPipeline({ errorRecovery: 'silent' });\n```\n\nAdditional safety with `maxRecursionDepth` (default: 100) to prevent stack overflow on deeply nested content.\n\n### API\n\n| Method | Description |\n|--------|-------------|\n| `parse(markdown)` | Parse markdown string to AST |\n| `render(nodes)` | Render AST to HTML string |\n| `renderMarkdown(markdown)` | Parse and render in one call |\n| `renderPage(title, nodes, options?)` | Render AST to full HTML page |\n| `getCustomCSS()` | Get custom CSS string from style config |\n| `getConfig()` | Get current pipeline configuration |\n\n## Architecture (v2)\n\nThe pipeline is built from modular stages, each with a clear design pattern and single responsibility:\n\n```\nMarkdown String\n │\n ▼\n┌──────────────────────────┐\n│ 1. Preprocessor Chain │ Chain of Responsibility\n│ (preprocessor.ts) │ Transforms raw markdown before lexing\n│ • ContainerBlock │ (e.g., ::: containers → HTML comments)\n└──────────┬───────────────┘\n │\n ▼\n┌──────────────────────────┐\n│ 2. marked.lexer() │ Third-party lexer\n└──────────┬───────────────┘\n │\n ▼\n┌──────────────────────────┐\n│ 3. Token Postprocessor │ Chain of Responsibility\n│ (token-postprocessor │ Restructures flat tokens → nested tree\n│ .ts) │ (e.g., comments → containerBlock)\n│ • ContainerBlock │\n└──────────┬───────────────┘\n │\n ▼\n┌──────────────────────────┐\n│ 4. Token Handlers │ Strategy Pattern\n│ (handlers/) │ Each marked token type has a dedicated\n│ • TokenHandlerRegistry│ handler, registered by type name.\n│ • CatchAllHandler │ Extensible at runtime via registry.\n└──────────┬───────────────┘\n │\n ▼\n ContentNode[]\n (AST)\n │\n ▼\n┌──────────────────────────┐\n│ 5. Renderer │ Strategy Pattern\n│ (renderer-strategies │ Each ContentNode type has its own\n│ .ts / lit-strategies │ render strategy — choose between:\n│ .ts) │ • HTMLRenderer (plain HTML strings)\n│ • NodeRendererStrategy│ • LitRenderer (Lit TemplateResult)\n│ • LitNodeRendererStrat│\n└──────────────────────────┘\n```\n\n### 1. Preprocessing (`preprocessor.ts`)\n\nThe `CompositePreprocessor` chains `Preprocessor` transforms that run on raw markdown **before** lexing. Built-in:\n\n- **`ContainerBlockPreprocessor`** — converts `:::tag#id.class` fences to `` HTML comment markers, so `marked` preserves them without affecting inner markdown parsing\n\nThe chain is extensible:\n\n```typescript\nimport { MarkdownParser, Preprocessor } from '@leadertechie/md2html';\n\nclass EmojiPreprocessor implements Preprocessor {\n readonly name = 'emoji';\n process(markdown: string): string {\n return markdown.replace(':smile:', '😊');\n }\n}\n\nconst parser = new MarkdownParser();\nparser.preprocessors.add(new EmojiPreprocessor());\n```\n\n### 2. Token Postprocessing (`token-postprocessor.ts`)\n\nThe `CompositeTokenPostprocessor` chains `TokenPostprocessor` transforms that run on the flat token array **after** lexing. Built-in:\n\n- **`ContainerBlockPostprocessor`** — collapses `` / `` markers into nested `containerBlock` tokens with proper parent-child structure (handles arbitrary nesting depth)\n\nCustom postprocessors:\n\n```typescript\nparser.postprocessors.add({\n name: 'filter-unwanted',\n process: (tokens) => tokens.filter(t => (t as any).type !== 'html')\n});\n```\n\n### 3. Token Handling — Strategy Pattern (`handlers/`)\n\nEach marked token type has its own `TokenHandler` class, registered in the `TokenHandlerRegistry`:\n\n```\nsrc/handlers/\n├── types.ts # TokenHandler interface + ParseContext\n├── registry.ts # TokenHandlerRegistry with catch-all fallback\n├── heading-handler.ts # h1-h6\n├── paragraph-handler.ts #
with inline image/HTML support\n├── list-handler.ts #
/\n├── image-handler.ts # ![]()
\n├── code-handler.ts # \n├── hr-handler.ts #
\n├── blockquote-handler.ts # \n├── html-handler.ts # raw HTML passthrough\n├── link-handler.ts # \n├── frontmatter-handler.ts# YAML frontmatter metadata\n├── container-block- # ::: container blocks\n│ handler.ts\n└── catchall-handler.ts # fallback for unregistered types\n```\n\n**Extending the parser** — register custom handlers without modifying internals:\n\n```typescript\nimport { MarkdownParser, TokenHandler } from '@leadertechie/md2html';\n\nconst parser = new MarkdownParser();\n\n// Override heading rendering\nconst customHeading: TokenHandler = {\n type: 'heading',\n handle: (token, ctx) => ({\n type: 'container',\n attributes: { tag: 'div', 'data-custom': 'true' },\n children: [{\n type: 'heading',\n content: ctx.processSlots(token.text as string),\n attributes: { level: String(token.depth) }\n }]\n })\n};\nparser.handlers.register(customHeading);\n\n// Remove a handler to skip token types\nparser.handlers.unregister('heading');\n\n// Replace the catch-all for unregistered token types\nparser.handlers.setCatchAll({\n type: '*',\n handle: (token) => ({\n type: 'text',\n content: `[fallback: ${token.type}]`\n })\n});\n```\n\n**Catch-all handler** — When a token type has no dedicated handler (e.g., `table`, `def`), the `CatchAllHandler` wraps it in a `` container so content is never silently lost. The `onUnhandledToken` callback notifies callers:\n\n```typescript\nconst parser = new MarkdownParser({\n onUnhandledToken: (type, token) => {\n console.warn(`[md2html] Unhandled token type: ${type}`);\n }\n});\n```\n\n### 4. Rendering — Strategy Pattern (`renderer-strategies.ts`, `lit-strategies.ts`)\n\nThe AST renderers use the same Strategy + Registry pattern as the token handlers:\n\n- **`HTMLRenderer`** — produces plain HTML strings. Uses `NodeRendererStrategy` / `RendererStrategyRegistry` for each node type. Supports `classPrefix`, `addHeadingIds`, and `emitScopeAnchors` styling.\n- **`LitRenderer`** — produces Lit `TemplateResult` objects. Uses `LitNodeRendererStrategy` / `LitStrategyRegistry`. Perfect for Lit web components.\n\nBoth registries are publicly accessible for customization:\n\n```typescript\nimport { HTMLRenderer, NodeRendererStrategy } from '@leadertechie/md2html';\n\nconst renderer = new HTMLRenderer({ classPrefix: 'my-' });\n\n// Register a custom strategy\nrenderer.strategies.register({\n type: 'custom',\n render: (node, renderChild, ctx) => `${node.content}`\n});\n```\n\nThe `LitRenderer.renderToHTMLString()` delegates to `HTMLRenderer` to avoid duplicating string rendering logic.\n\n### 5. Context Factory (`context-factory.ts`)\n\nThe `createParseContext()` pure function separates context construction from the parser class. It bridges parser services (image processing, slot resolution, HTML sanitization) to token handlers via the `ParserServices` interface. This makes the context testable in isolation and decouples handler logic from parser internals.\n\n### Source Map\n\n```\nsrc/\n├── parser.ts # Orchestrator: coordinates pre/post-processing + token handling\n├── preprocessor.ts # Chain of Responsibility: markdown transforms before lexing\n├── token-postprocessor.ts # Chain of Responsibility: token transforms after lexing\n├── context-factory.ts # Factory: creates ParseContext for token handlers\n├── handlers/ # Strategy: per-token-type ContentNode producers\n│ ├── types.ts\n│ ├── registry.ts\n│ ├── heading-handler.ts\n│ ├── paragraph-handler.ts\n│ ├── list-handler.ts\n│ ├── image-handler.ts\n│ ├── code-handler.ts\n│ ├── hr-handler.ts\n│ ├── blockquote-handler.ts\n│ ├── html-handler.ts\n│ ├── link-handler.ts\n│ ├── frontmatter-handler.ts\n│ ├── container-block-handler.ts\n│ └── catchall-handler.ts\n├── renderer.ts # HTMLRenderer: transforms ContentNodes to plain HTML\n├── renderer-strategies.ts # Strategy: per-node-type HTML string renderers\n├── lit-renderer.ts # LitRenderer: transforms ContentNodes to Lit TemplateResult\n├── lit-strategies.ts # Strategy: per-node-type Lit TemplateResult renderers\n├── visitor.ts # Visitor: tree traversal utilities\n├── factory.ts # NodeFactory: ContentNode builder API\n├── pipeline.ts # Facade: high-level MarkdownPipeline API\n├── types.ts # Core types: ContentNode, MarkdownContent, configs\n└── telemetry-init.ts # Shared logger initialization\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}