Markdown sanitization chain
Skill fabioc-aloha/Alex_ACT_Edition/.github/skills/markdown-sanitization-chain
Render user-supplied markdown safely — marked.js → DOMPurify → Mermaid (order matters; skipping the sanitizer is XSS)From its SKILL.md
npx -y skills add fabioc-aloha/Alex_ACT_Edition --skill markdown-sanitization-chainAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
3.4 KB, 783 tokens by cl100k_base, as published. Nobody here has run it
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
innerHTMLwith 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
| Mistake | Consequence |
|---|---|
| Skip DOMPurify ("it's internal content") | XSS from any content source |
| Sanitize after Mermaid renders | Mermaid-injected scripts execute |
Use innerHTML without sanitization anywhere | Classic XSS |
| Trust localStorage / URL params | User-controlled XSS payloads |
DOMPurify Configuration
const config = {
ADD_TAGS: ['mermaid'], // preserve diagram tags
ADD_ATTR: ['onclick'], // only if absolutely needed
FORBID_TAGS: ['style', 'script'], // explicit blocklist
FORBID_ATTR: ['onerror', 'onload'],
};
Verification Checklist
- Markdown parser runs first
- DOMPurify runs before DOM insertion
- Diagram renderer runs after sanitization
- No raw
innerHTMLwithout sanitization anywhere in the surface - 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 this skill by 2026-08-26 (90 days) or sooner if any of the following fires: DOMPurify or marked.js publishes a breaking change that invalidates the documented chain order; a real XSS payload bypasses the chain in production use; or Mermaid changes its render-time HTML interface in a way that makes the post-sanitization step unsafe.
What ships with it
Read from the repository
Just SKILL.md. No reference files, no scripts.