Security #

Markdown rendered in a browser is often untrusted: comments, chat messages, CMS content, LLM output. This page lists what mdlib-pure guarantees by default and what depends on your configuration.

Defaults #

When raw HTML is enabled #

html: true passes raw HTML through unchanged. Use it only for trusted input, or with a sanitizer:

import DOMPurify from 'dompurify'
createMarkdown({ html: true, sanitize: DOMPurify.sanitize })

• render() applies sanitize to the final HTML string.
• toVNodes() (and so the React/Vue/Preact adapter) applies sanitize to every raw HTML node: each fragment reaching dangerouslySetInnerHTML or innerHTML has been sanitized.
• renderTo() builds DOM nodes directly when the tree has no raw HTML. With raw HTML (or a plugin emitting r.raw()), it serializes and assigns innerHTML, after sanitize. This is the only innerHTML in the library besides the entity decoder (which only ever receives [a-z0-9] names).
• The GFM plugin includes tagfilter: <script>, <iframe>, <style>, <textarea>, <title>, <xmp>, <noembed>, <noframes> and <plaintext> are neutralized. It is a GitHub-compatible filter, not a sanitizer: event handler attributes survive it.

URL policy #

The default isSafeUrl(url, kind) is an allowlist:

Rejected URLs render as href="" / src="": the link text stays visible. Note that GFM autolinks like ftp://host are therefore not clickable by default.

Replace or extend the policy:

import { createMarkdown, isSafeUrl } from 'mdlib-pure'

createMarkdown({
  allowUrl: (url, kind) => isSafeUrl(url, kind) || /^vscode:/i.test(url),
})

Mermaid diagrams #

The mermaid plugin itself only outputs escaped text. The SVG is created and inserted by Mermaid, outside mdlib-pure's DOM-safe path, so its safety is Mermaid's: renderMermaid uses securityLevel: 'strict' by default (labels sanitized, no click callbacks); for untrusted input consider 'sandbox' and keep Mermaid up to date.

Web Components #

<mdlib-markdown> and <mdlib-editor> (mdlib-pure/element) render through renderTo() with the defaults above, the editor's live preview included.

• Attributes only choose plugins and a named config. html, sanitize, allowUrl and highlight come only from defineElements({ configs }), written in JavaScript: markup or content that sets attributes cannot turn raw HTML on or loosen the URL policy.
• Math is typeset by KaTeX with its defaults (trust: false: no \href, no \includegraphics); diagrams by Mermaid with securityLevel: 'strict'. Both write into the element, outside mdlib-pure's DOM-safe path.
• The loaders are yours: mermaid and katex import what you give them, and katexStylesheet is fetched and added to document.adoptedStyleSheets. Point them at files you serve (no CDN is hard-coded).
• Framework wrappers built on the elements add their own notes: Blazor, Angular.

DOM clobbering #

Element ids become globals (window.config), so ids derived from content could let a document shadow names your scripts read. The headings plugin produces clean ids by default (#install); for untrusted input, prefix them as GitHub does: headings({ prefix: 'user-content-' }). GFM footnote ids are already prefixed with fn-/fnref-.

Plugins #

Plugins run with full trust. A plugin must:

• pass URLs through r.url(url, kind);
• return text as plain strings (escaped by the serializer), never build HTML strings from input;
• use r.raw() only for HTML it fully controls;
• keep its parsing linear (see rule 8 in AGENTS.md).

Reporting #

Report vulnerabilities privately to the maintainer (Michele Polo) rather than in public issues.