marked/docs/USING_ADVANCED.md

Marked instance

By default, Marked stores options and extensions in the global scope. That means changing the options in one script will also change the options in another script since they share the same instance.

If you don't want to mutate global scope, you can create a new instance of Marked to ensure options and extensions are locally scoped.

import { Marked } from 'marked';
const marked = new Marked([options, extension, ...]);

Argument	Type	Notes
options	object	The same arguments that can be passed to marked.use

Be careful: marked.use(...) should not be used in a loop or function. It should only be used directly after new Marked is created or marked is imported.

The parse function

import { marked } from 'marked';
marked.parse(markdownString [,options])

Argument	Type	Notes
markdownString	string	String of markdown source to be compiled.
options	object	Hash of options. Can also use marked.use to set global options

Alternative using reference

// Create reference instance
import { marked } from 'marked';

// Set options
marked.use({
  async: true,
  pedantic: false,
  gfm: true,
});

// Compile
console.log(marked.parse(markdownString));

Options

Member	Type	Default	Since	Notes
async	boolean	false	4.1.0	If true, walkTokens functions can be async and marked.parse will return a promise that resolves when all walk tokens functions resolve.
breaks	boolean	false	v0.2.7	If true, add <br> on a single line break (copies GitHub behavior on comments, but not on rendered markdown files). Requires gfm be true.
gfm	boolean	true	v0.2.1	If true, use approved GitHub Flavored Markdown (GFM) specification.
pedantic	boolean	false	v0.2.1	If true, conform to the original markdown.pl as much as possible. Don't fix original markdown bugs or behavior. Turns off and overrides gfm.
renderer	object	new Renderer()	v0.3.0	An object containing functions to render tokens to HTML. See extensibility for more details.
silent	boolean	false	v0.2.7	If true, the parser does not throw any exception or log any warning. Any error will be returned as a string.
tokenizer	object	new Tokenizer()	v1.0.0	An object containing functions to create tokens from markdown. See extensibility for more details.
walkTokens	function	null	v1.1.0	A function which is called for every token. See extensibility for more details.

Old Options

Member	Type	Default	Since	Notes
smartLists (removed)	boolean	false	v0.2.8	Removed in v3.0.0.
baseUrl (removed)	string	null	v0.3.9	Removed in v8.0.0 use marked-base-url to prefix url for any relative link.
headerIds (removed)	boolean	true	v0.4.0	Removed in v8.0.0 use marked-gfm-heading-id to include an id attribute when emitting headings (h1, h2, h3, etc).
headerPrefix (removed)	string	''	v0.3.0	Removed in v8.0.0 use marked-gfm-heading-id to add a string to prefix the id attribute when emitting headings (h1, h2, h3, etc).
highlight (removed)	function	null	v0.3.0	Removed in v8.0.0 use marked-highlight to add highlighting to code blocks.
langPrefix (removed)	string	'language-'	v0.3.0	Removed in v8.0.0 use marked-highlight to prefix the className in a <code> block. Useful for syntax highlighting.
mangle (removed)	boolean	true	v0.3.4	Removed in v8.0.0 use marked-mangle to mangle email addresses.
sanitize (removed)	boolean	false	v0.2.1	Removed in v8.0.0 use a sanitize library, like DOMPurify (recommended), sanitize-html or insane on the output HTML!
sanitizer (removed)	function	null	v0.3.4	Removed in v8.0.0 use a sanitize library, like DOMPurify (recommended), sanitize-html or insane on the output HTML!
smartypants (removed)	boolean	false	v0.2.9	Removed in v8.0.0 use marked-smartypants to use "smart" typographic punctuation for things like quotes and dashes.
xhtml (removed)	boolean	false	v0.3.2	Removed in v8.0.0 use marked-xhtml to emit self-closing HTML tags for void elements (<br/>, <img/>, etc.) with a "/" as required by XHTML.

Known Extensions

Marked can be extended using custom extensions. This is a list of extensions that can be used with marked.use(extension).

Name	Package Name	Description
Admonition	marked-admonition-extension	Admonition extension
Alert	marked-alert	Enables GFM alerts
Base URL	marked-base-url	Prefix relative urls with a base URL.
Bidi	marked-bidi	Add Bidirectional text support to the HTML
Code Format	marked-code-format	Formatting code blocks using Prettier
Code JSX Renderer	marked-code-jsx-renderer	Render JSX code blocks using a custom renderer and components
Code Preview	marked-code-preview	Transform code blocks into code previews
Custom Heading ID	marked-custom-heading-id	Specify a custom heading id in headings with the Markdown Extended Syntax # heading {#custom-id}
Directive	marked-directive	Supports directives syntax
Emoji	marked-emoji	Add emoji support like on GitHub
Extended Tables	marked-extended-tables	Extends the standard Github-Flavored tables to support advanced features: Column Spanning, Row Spanning, Multi-row headers
Footnote	marked-footnote	Enables GFM footnotes
GFM Heading ID	marked-gfm-heading-id	Use github-slugger to create the heading IDs and allow a custom prefix.
Highlight	marked-highlight	Highlight code blocks
Katex Code	marked-katex-extension	Render katex code
LinkifyIt	marked-linkify-it	Use linkify-it for urls
Mangle	marked-mangle	Mangle mailto links with HTML character references
Misskey-flavored Markdown	marked-mfm	Custom extension for Misskey-flavored Markdown.
More Lists	marked-more-lists	Support for alphabetical and roman numeral ordered lists
Plaintify	marked-plaintify	Converts Markdown to Plaintext
Shiki	marked-shiki	Integrating Shiki syntax highlighting
Sequential Hooks	marked-sequential-hooks	Enables the sequential preprocessing and post-processing within sequential hooks
Smartypants	marked-smartypants	Use smartypants to use "smart" typographic punctuation for things like quotes and dashes.
Smartypants lite	marked-smartypants-lite	A faster lighter version of marked-smartypants that doesn't use any external dependencies to create "smart" typographic punctuation for things like quotes and dashes.
XHTML	marked-xhtml	Emit self-closing HTML tags for void elements (<br/>, <img/>, etc.) with a "/" as required by XHTML.

Inline Markdown

You can parse inline markdown by running markdown through marked.parseInline.

const blockHtml = marked.parse('**strong** _em_');
console.log(blockHtml); // '<p><strong>strong</strong> <em>em</em></p>'

const inlineHtml = marked.parseInline('**strong** _em_');
console.log(inlineHtml); // '<strong>strong</strong> <em>em</em>'

Highlighting

Use marked-highlight to highlight code blocks.

Workers

To prevent ReDoS attacks you can run marked on a worker and terminate it when parsing takes longer than usual.

Marked can be run in a worker thread on a node server, or a web worker in a browser.

Node Worker Thread

// markedWorker.js

import { marked } from 'marked';
import { parentPort } from 'worker_threads';

parentPort.on('message', (markdownString) => {
  parentPort.postMessage(marked.parse(markdownString));
});

// index.js

import { Worker } from 'worker_threads';
const markedWorker = new Worker('./markedWorker.js');

const markedTimeout = setTimeout(() => {
  markedWorker.terminate();
  throw new Error('Marked took too long!');
}, timeoutLimit);

markedWorker.on('message', (html) => {
  clearTimeout(markedTimeout);
  console.log(html);
  markedWorker.terminate();
});

markedWorker.postMessage(markdownString);

Web Worker

Note

: Web Workers send the payload from postMessage in an object with the payload in a .data property

// markedWorker.js

importScripts('path/to/marked.min.js');

onmessage = (e) => {
  const markdownString = e.data
  postMessage(marked.parse(markdownString));
};

// script.js

const markedWorker = new Worker('./markedWorker.js');

const markedTimeout = setTimeout(() => {
  markedWorker.terminate();
  throw new Error('Marked took too long!');
}, timeoutLimit);

markedWorker.onmessage = (e) => {
  clearTimeout(markedTimeout);
  const html = e.data;
  console.log(html);
  markedWorker.terminate();
};

markedWorker.postMessage(markdownString);

CLI Extensions

You can use extensions in the CLI by creating a new CLI that imports marked and the marked binary.

// file: myMarked
#!/usr/bin/node

import { marked } from 'marked';
import customHeadingId from 'marked-custom-heading-id';

marked.use(customHeadingId());

import 'marked/bin/marked';

$ ./myMarked -s "# heading {#custom-id}"
<h1 id="custom-id">heading</h1>