USING ADVANCED

<h2 id="instance">Marked instance</h2>

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.
<a href="#options">options</a>	`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));

<h2 id="options">Options</h2>

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 `
`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.

<h2 id="extensions">Known Extensions</h2>

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
ABCjs	`abcjs`	ABCjs sheet music rendering
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
CJK Breaks	`marked-cjk-breaks`	Suppress soft linebreaks between east asian characters
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
HTML Renderer	`marked-html-renderer`	Output HTML Elements instead of a string
Jira Renderer	`marked-jira`	Output Jira compatible format
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
Marked Responsive Images	`marked-responsive-images`	Generate responsive (`srcset`) images based on structured filenames
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
Token Position	`marked-token-position`	Adds a `position` field to each token with `start` and `end` properties containing `line`, `column`, and `offset`
Typograf	`marked-typograf`	Use typograf as a more powerful and extendable alternative to Smartypants for creating “smart” typographic punctuation, such as quotes and dashes
XHTML	`marked-xhtml`	Emit self-closing HTML tags for void elements (<br/>, <img/>, etc.) with a "/" as required by XHTML

<h2 id="user-examples">User Examples</h2> <details> <summary>Marked can render on-page content as markdown in the browser.</summary>

html

<!DOCTYPE html>
<html>
 <head>
   <!-- Suggested stylesheet -->
   <link rel="stylesheet" 
    href="https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/5.8.1/github-markdown.min.css"
    crossorigin="anonymous" referrerpolicy="no-referrer" />

   <title>Marked for the full page</title>
 </head>

 <body> 
  <textarea id="markdown-source" style="display: none;">
# Title

Lots of text using **markdown syntax.**
  </textarea>
  <div id="content" class="markdown-body"></div>
  
  <script src="https://cdn.jsdelivr.net/npm/marked/lib/marked.umd.js"></script>
  <script>
    const source = document.getElementById('markdown-source').value;
    
    // Parse the markdown and render it into the content div.
    document.getElementById('content').innerHTML = marked.parse(source);
  </script>
 </body>
</html>

</details> <h2 id="inline">Inline Markdown</h2>

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>'

<h2 id="highlight">Highlighting</h2>

Use marked-highlight to highlight code blocks.

<h2 id="workers">Workers</h2>

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.umd.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);

<h2 id="cli-extensions">CLI Extensions</h2>

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>

The parse function

Alternative using reference

Old Options

Node Worker Thread

Web Worker

The `parse` function