Rehype-raw

What Rehype-raw Does in a Markdown Pipeline

Rehype-raw is the step that turns raw HTML embedded in Markdown into actual DOM-like elements. That makes mixed Markdown and HTML content render correctly, but it also means the pipeline stops treating that markup as inert text. The term matters because the same feature that improves formatting can also reopen injection paths if trust boundaries are loose.

Why It Changes the Security Model

Once raw HTML is reparsed, the security question shifts from "is this text escaped?" to "is this markup safe to execute or render?" That distinction matters for content coming from users, CMS fields, documentation systems, comment streams, and any workflow where untrusted input can reach the renderer.

When rehype-raw is used, safety depends on what happens before and after the parse step, especially whether dangerous elements and attributes are removed or neutralised. The parser itself is not the protection layer; it is the mechanism that makes later sanitisation necessary.

Common Failure Modes

The main failure mode is assuming that Markdown conversion alone has made the content safe. If raw HTML is allowed through without a strong sanitizer, attackers may be able to introduce scripts, event handlers, malicious links, or other executable markup that survives rendering.

Another common problem is partial sanitisation, where the pipeline removes obvious tags but leaves risky attributes, protocol handlers, or nested markup combinations intact. That can create a false sense of safety because the output looks clean while still containing exploitable behaviour.

Where It Fits in Secure Content Processing

Rehype-raw belongs in a broader rendering chain that treats untrusted content as a security input, not just a formatting input. It is most defensible when the system has clear content provenance, explicit allowlists, and a sanitizer that runs after HTML is parsed into real elements.

In practice, the right mental model is: parse first only if you must, then inspect and constrain the resulting structure before it reaches the browser. The feature is useful because it preserves author intent, but that same power means the pipeline must be designed around trust reduction rather than convenience alone.

Risk and Threat Considerations

Rehype-raw can create a browser-execution risk when untrusted HTML is reparsed without effective post-parse sanitisation. The danger is not the Markdown step itself, but the fact that raw markup regains structure and behaviour once it is turned into real elements.

Failure mechanism: An attacker supplies HTML that is treated as data in one stage, then becomes active markup after parsing, allowing dangerous elements, attributes, or URLs to survive into the rendered page.

Impact: The result can be cross-site scripting, malicious redirects, content spoofing, or compromise of the reader's session and trust in the page.

Practitioner Guidance

What to watch for: Treat rehype-raw as a high-trust transformation step only when the input source is controlled. If authorship is mixed or user-generated content is involved, the sanitizer and its allowlist become the real control point, not the Markdown parser.

Governance implication: Own the decision about which HTML is permitted, which attributes are stripped, and where in the pipeline sanitisation occurs. A safe deployment usually depends on a documented content policy, not on developer assumptions about what the renderer will ignore.

Related resources from NHI Mgmt Group

• Why do identity signals matter more than raw security telemetry?
• Why do raw Terraform resources create governance risk?
• What breaks when raw secrets are exposed to LLM workflows?
• What breaks when an LLM can call raw backend APIs directly?