ngx-markdown

ngx-markdown is an Angular library providing a markdown component, attribute directive, and async pipe that parse Markdown content into sanitized HTML using Marked under the hood. It supports static markdown transcluded directly in templates, remote content fetched over HttpClient, and reactive variable bindings, exposing load, error, and ready output events plus an injectable MarkdownService for programmatic parsing and rendering.

Beyond core parsing, it layers in optional plugins for real-world documentation needs: Prism.js syntax highlighting with line-numbers, line-highlight, and command-line variants, KaTeX math rendering, Mermaid diagrams, GitHub-style emoji shortcodes, and one-click copy-to-clipboard for code blocks. Every plugin is opt-in and independently installable, configured globally via provideMarkdown() or overridden per component.

What You Get

• Standalone-compatible MarkdownComponent, markdown attribute directive, and MarkdownPipe for rendering markdown three different ways from the same underlying parser
• An injectable MarkdownService for programmatic parsing, rendering, custom renderer overrides, and syntax highlighting outside of templates
• provideMarkdown() configuration function for wiring an HTTP loader, sanitizer, Marked options/extensions, KaTeX, Mermaid, and clipboard providers via Angular DI
• Optional Prism.js, KaTeX, Mermaid, Emoji-Toolkit, and Clipboard.js plugin integrations, each independently installable and activated per component
• Built-in XSS-safe sanitization via Angular’s DomSanitizer, with a pluggable custom-sanitizer hook (e.g. DOMPurify) and a documented opt-out
• A live demo application and StackBlitz sandbox demonstrating every plugin and configuration option in context

Common Use Cases

• Rendering in-app documentation and changelogs loaded from remote Markdown files
• Displaying user-generated Markdown content (comments, chat messages, notes) safely with sanitization on by default
• Building technical blogs or docs pages with syntax-highlighted, copyable code blocks
• Rendering math-heavy content with KaTeX inside an Angular application
• Visualizing Mermaid diagrams and flowcharts embedded directly in Markdown documentation

Under The Hood

Architecture The library is organized as a flat lib/src directory exposing a single Angular library entry point (public_api.ts) built around one central MarkdownService that owns all parsing/rendering logic, with three thin presentation layers — MarkdownComponent, the markdown attribute directive, and MarkdownPipe — that all delegate to that same service, and small config modules (marked-options.ts, katex-options.ts, mermaid-options.ts, clipboard-options.ts, sanitize-options.ts) that each define an InjectionToken for DI-based configuration. The service lazily extends the shared Marked Renderer per feature (extendsRendererForKatex, extendsRendererForMermaid, extendsRendererForExtensions), stamping boolean flags onto the renderer object itself to avoid re-registering the same Marked extension twice — a deliberate workaround, documented in code comments, for Marked’s global rather than instance-scoped extension API. Because every consumer shares one service with no independent logic, a change to the core parse/render pipeline propagates to the component, directive, and pipe simultaneously.

Tech Stack Built as an Angular library (targeting Angular 22 and its Vite-based application builder) using ng-packagr to compile into a standalone Angular Package Format artifact, alongside a companion Angular CLI demo app used both for local development and the published GitHub Pages demo. The core runtime dependency is marked (^18) for Markdown-to-HTML parsing, with optional integrations for prismjs (syntax highlighting), katex plus marked-katex-extension (math), mermaid (diagrams), emoji-toolkit (emoji shortcodes), and clipboard (copy-to-clipboard) — each loaded as a global script rather than a bundled import, referenced in the library via declare let globals instead of hard dependencies. Tooling is TypeScript ~6.0 with angular-eslint/typescript-eslint for linting, Karma/Jasmine for unit tests, and CircleCI as the primary CI provider (with GitHub Actions alongside) plus Coveralls for coverage reporting.

Code Quality Every public surface has a paired .spec.ts file — markdown.service.spec.ts alone runs to over 1,300 lines covering parse options, plugin gating, sanitizer branches, and renderer-extension idempotency, alongside spec files for the component, module, pipe, and clipboard button, all run via Karma/Jasmine with coverage reported to Coveralls. Error handling is explicit and typed: missing optional dependencies (Prism, KaTeX, Mermaid, Clipboard.js, JoyPixels) throw named, exported error-message constants rather than failing silently, and browser-only features degrade gracefully during server-side rendering via isPlatformBrowser checks. TypeScript is strict, the public options interfaces are fully typed, and ESLint (angular-eslint plus typescript-eslint, with a checkstyle CI formatter) gates every change alongside a dedicated type-check script.

API Design The public API surface is deliberately small and orthogonal — one component, one directive, one pipe, one service, and one provideMarkdown() function — letting consumers start with zero configuration and progressively opt into plugins (katex, mermaid, emoji, clipboard, lineNumbers, and more) as boolean template attributes rather than requiring upfront module setup. Naming stays consistent across the three consumption styles, and the library supports advanced DI patterns — typed injection tokens for every optional dependency, factory-based provider overrides, and a documented pattern for overriding individual Marked token renderers — while keeping the zero-config path genuinely one line. The tradeoff is that several plugins must be wired in manually via global scripts in angular.json rather than pure npm imports, a manual step that is well-documented but adds friction per plugin adopted.