Markdown Sanitization Chain

Battle-tested via production XSS incident. The order of markdown → sanitize → diagram render is non-negotiable when content comes from users.

When to Use

• An app renders markdown supplied by users (comments, docs UI, embedded editors)
• You're about to call innerHTML with markdown-derived HTML
• Mermaid or another diagram renderer runs in the browser
• Security review on a markdown-rendering surface

Why It Matters

Markdown renderers (marked.js, markdown-it) convert markdown to HTML but do not sanitize it. Diagram renderers (Mermaid, PlantUML) execute after sanitizers run, which can re-introduce attack vectors. Order matters critically.

The Rule

Always: marked.js → DOMPurify → Mermaid (post-render).

1. Parse markdown to HTML        (marked.js)
2. Sanitize HTML                 (DOMPurify)
3. Insert sanitized HTML into DOM
4. Render diagrams on the now-sanitized DOM (Mermaid.run())

Never skip the sanitizer even if content is "trusted." Trust gets revoked when the threat model changes; the chain stays.

Implementation

import { marked } from 'marked';
import DOMPurify from 'dompurify';
import mermaid from 'mermaid';

async function renderMarkdown(content, container) {
  // Step 1: parse markdown to HTML
  const rawHtml = marked.parse(content);

  // Step 2: sanitize BEFORE inserting into the DOM
  const cleanHtml = DOMPurify.sanitize(rawHtml, {
    ADD_TAGS: ['mermaid'], // allow mermaid tags through
  });

  // Step 3: insert sanitized HTML
  container.innerHTML = cleanHtml;

  // Step 4: render diagrams on sanitized DOM
  await mermaid.run({ nodes: container.querySelectorAll('.mermaid') });
}

Common Mistakes

DOMPurify Configuration

const config = {
  ADD_TAGS: ['mermaid'],            // preserve diagram tags
  ADD_ATTR: ['class'],              // preserve diagram class hooks only
  FORBID_TAGS: ['style', 'script'], // explicit blocklist
  FORBID_ATTR: ['onclick', 'onerror', 'onload'],
};

Do not allow on* event attributes by default. If a product genuinely needs an event handler, bind it in trusted application code after sanitization instead of allowing user-supplied event attributes through DOMPurify.

Verification Checklist

• Markdown parser runs first
• DOMPurify runs before DOM insertion
• Diagram renderer runs after sanitization
• Review DOM insertion paths for unsanitized input. scripts/lint-innerhtml.cjs (in this skill's scripts/ directory) is a heuristic aid for direct dot-property innerHTML/outerHTML assignments. It recognizes whole sanitizer calls and static literals, and flags indirect or composed expressions for review. A clean scan does not establish safety: inspect data flow, dynamic/bracket-property sinks, parser limitations, and sanitizer configuration separately.
• Tested with <img src=x onerror=alert(1)> payload

Related

• markdown-mermaid — markdown + Mermaid style guide
• markdown-mermaid § Mode Fragility — silent render failures
• lint-clean-markdown — author-side hygiene

Would Revise If

Revisit the repaired configuration if DOMPurify or marked.js changes the documented chain behavior, an event attribute or unsafe URL survives the tested configuration, or Mermaid's post-sanitization output introduces executable user content.