Marked.js Markdown Parser

Common errors

• ReferenceError: require is not defined

  cause Attempting to use `require()` for Marked.js in an ECMAScript Module (ESM) context (e.g., `"type": "module"` in package.json, or `.mjs` files) where CommonJS `require` is not natively available.
  fix Change your import statement to `import { marked } from 'marked';` or `import { parse } from 'marked';` for ESM environments.

• TypeError: marked.parse is not a function

  cause This usually occurs when attempting to call `marked.parse()` after importing `marked` as a default export (`import marked from 'marked';`) in an environment where `marked` is a named export object, or when using an incorrect UMD/browser script.
  fix For Node.js/bundlers using ESM, ensure you use `import { marked } from 'marked';` and then call `marked.parse()`. If using the browser UMD bundle (`marked.umd.js`), the `marked` global object should have the `parse` method directly.

• Unescaped HTML or XSS vulnerability detected in output.

  cause Markdown input contained malicious HTML or scripts (e.g., `<script>alert('xss')</script>`), and the output HTML was rendered without proper sanitization. Marked.js does not sanitize its output by design.
  fix Integrate a robust HTML sanitization library, such as DOMPurify, and run the `marked.parse()` output through it before rendering. Example: `DOMPurify.sanitize(marked.parse(input))`.

Warnings

• breaking Marked.js versions 18.0.0 and above now depend on TypeScript 6.0.2. Projects using older TypeScript versions or specific TS features that are incompatible with this version may encounter compilation issues. Ensure your project's TypeScript setup is compatible.
  Fix: Upgrade your project's TypeScript version to 6.0.2 or newer, or ensure your tsconfig.json is configured to support the types.
• breaking Version 17.0.0 introduced significant internal changes to how tokenizers and renderers operate, specifically affecting consecutive text tokens in lists, the `listItem` renderer, and the addition of a `CheckboxToken` with new `type` and `raw` properties. Custom extensions that directly interact with or override these internal mechanisms will likely require updates.
  Fix: Review custom Marked.js extensions, especially those dealing with lists, tokens, or renderers, and update them to align with the new internal token and renderer structures as documented in the Marked.js extensibility guide.
• gotcha Marked.js explicitly does NOT sanitize its HTML output. Directly rendering output from untrusted Markdown input can lead to Cross-Site Scripting (XSS) vulnerabilities. This is a deliberate design choice for performance and flexibility.
  Fix: ALWAYS sanitize the HTML output using a dedicated sanitization library like DOMPurify (recommended) or sanitize-html before rendering it in a browser context. This step is critical for security.
• gotcha Marked.js only supports current and LTS (Long Term Support) Node.js versions. Using End-of-Life (EOL) Node.js versions may lead to unexpected behavior, compatibility issues, or even prevent the library from functioning correctly at any point.
  Fix: Ensure your Node.js environment is always an actively maintained LTS or current release. Refer to the official Node.js releases page for up-to-date information.
• gotcha Previous versions of Marked.js (e.g., v17.0.4, v17.0.5) contained fixes for Redos (Catastrophic Backtracking) vulnerabilities in its internal regular expressions. While fixed in current releases, this highlights the importance of keeping the library updated to protect against potential Denial-of-Service attacks when parsing malicious or overly complex Markdown input.
  Fix: Regularly update Marked.js to the latest stable version to benefit from security patches and performance improvements. Avoid crafting custom regular expressions for Markdown parsing without thorough ReDoS testing.

Install

• npm install marked npm
• yarn add marked yarn
• pnpm add marked pnpm

Imports

• marked
  wrong:

  const marked = require('marked');

  correct:

  import { marked } from 'marked';

  For ESM environments, `marked` is a named export containing the `parse` function and other utilities. CommonJS `require` should generally be avoided in modern Node.js projects unless explicit CJS interop is needed.
• parse
  wrong:

  import marked from 'marked'; // then marked('text')

  correct:

  import { parse } from 'marked';

  The primary parsing function can be directly imported as a named export `parse` for convenience. Be aware that importing `marked` as a default might lead to issues if the main export structure changes or if using older bundlers.
• MarkedExtension
  wrong:

  import { MarkedExtension } from 'marked'; // for runtime usage

  correct:

  import type { MarkedExtension } from 'marked';

  This is a TypeScript type definition used for creating custom extensions. It should only be imported using `import type` to avoid bundling unnecessary runtime code.

Quickstart

Demonstrates basic Markdown parsing with Marked.js, including critical HTML sanitization using DOMPurify and configuring options.

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

const markdownInput = `# Hello from Marked.js!

This is a paragraph with **bold** and *italic* text.

- List item 1
- List item 2

### Code Example

```javascript
function greet(name) {
  console.log('Hello, ' + name + '!');
}
greet('World');
```

<script>alert('XSS attempt!');</script>`;

// Parse the markdown to HTML
const unsafeHTML = marked.parse(markdownInput);

// Sanitize the HTML output (CRITICAL STEP for untrusted input)
const safeHTML = DOMPurify.sanitize(unsafeHTML);

console.log('--- Unsafe HTML (for demonstration) ---\n', unsafeHTML);
console.log('\n--- Safe HTML (after DOMPurify) ---\n', safeHTML);

// Example with custom options
marked.setOptions({
  gfm: true, // GitHub Flavored Markdown
  breaks: true, // Interpret line breaks as <br/>
  headerIds: false // Disable auto-generated header IDs
});

const customParsedHTML = DOMPurify.sanitize(marked.parse(`## Custom Options Test\nLine 1\nLine 2`));
console.log('\n--- HTML with Custom Options ---\n', customParsedHTML);