remark-html

remark-html is a compiler plugin for the unified/remark ecosystem that turns a parsed markdown syntax tree (mdast) into an HTML string. Rather than requiring you to wire together remark-rehype and rehype-stringify by hand, it bundles the mdast-to-hast conversion, output sanitization, and HTML serialization into a single .use() call, making it the fastest path from markdown source to safe HTML output.

Under the hood it runs each mdast tree through mdast-util-to-hast to produce a hast tree, sanitizes that tree by default with hast-util-sanitize’s safe schema (blocking script tags, inline event handlers, and other injection vectors), and hands the result to hast-util-to-html for stringification. The sanitize option accepts false to allow raw/dangerous HTML through, or a custom schema object to loosen or tighten specific rules, while handlers lets consumers override how individual mdast node types compile to hast.

What You Get

• One-step markdown-to-HTML compilation as a single .use() call in a unified pipeline
• Safe-by-default output sanitization via hast-util-sanitize, blocking script injection and dangerous attributes
• A configurable sanitize option to loosen the schema or fully disable sanitization when trusted input is guaranteed
• A custom handlers option to override how specific mdast node types are turned into hast/HTML

Common Use Cases

• Rendering user-authored markdown (comments, docs, README previews) into safe HTML for direct display
• Quick prototyping of a markdown-to-HTML pipeline without manually chaining remark-rehype and rehype-stringify
• Static site generators and CMS content pipelines that need markdown compiled to HTML at build time
• Server-side rendering of markdown content where output must be sanitized before reaching the browser

Under The Hood

Architecture The package is a single-file unified plugin (lib/index.js) that attaches a compiler function to the processor’s this context, following unified’s standard plugin-attaches-a-compiler pattern. The compiler takes the mdast tree, converts it to a hast tree via mdast-util-to-hast, conditionally runs it through hast-util-sanitize unless sanitize: false was passed, and serializes the result with hast-util-to-html. There is no internal layering beyond this one function — all real transformation logic is delegated to three purpose-built syntax-tree utilities from the wider unified ecosystem, keeping the plugin itself thin and single-responsibility.

Tech Stack This is an ESM-only package ("type": "module") with five runtime dependencies, all from the unified/syntax-tree family: unified, mdast-util-to-hast, hast-util-sanitize, hast-util-to-html, and @types/mdast. Types are authored as JSDoc comments and compiled to declarations via tsc --build, avoiding a separate TypeScript source tree while still shipping a fully typed Options export. Dev tooling includes xo (a strict ESLint preset) plus prettier for formatting, c8 for coverage, and Node’s built-in node:test runner for tests — no bundler is needed since the package ships its raw ESM files directly via the exports field.

Code Quality Tests in test/index.js exercise the plugin against the full CommonMark specification fixture set (commonmark.json) alongside hand-written cases for unknown node handling and the sanitize/handlers options, using node:assert/strict for assertions. Coverage is enforced at 100% via c8, and static type coverage is enforced at 100% via the type-coverage tool on top of the JSDoc-derived types. Linting runs through xo with Prettier integration, and a GitHub Actions workflow (main) provides CI. No error-swallowing patterns were found — the compiler propagates any errors from the underlying conversion utilities directly through unified’s own error handling.

API Design The entire public surface is one default export (remarkHtml) plus a typed Options object covering handlers, sanitize, and any pass-through hast-util-to-html options. Its value is ergonomic rather than novel: it collapses what would otherwise be a three-plugin chain (remark-rehype + rehype-sanitize + rehype-stringify) into one call with a safe default, at the cost of less flexibility than composing those plugins individually. Getting started requires no boilerplate beyond .use(remarkHtml), and the README documents every option with a runnable example.