![remark][file-logo]

[![Build][badge-build-image]][badge-build-url] [![Coverage][badge-coverage-image]][badge-coverage-url] [![Downloads][badge-downloads-image]][badge-downloads-url] [![Size][badge-size-image]][badge-size-url]

remark is a tool that transforms markdown with plugins. These plugins can inspect and change your markup. You can use remark on the server, the client, CLIs, deno, etc.

Feature highlights

• [x] [compliant][section-syntax] — 100% to CommonMark, 100% to GFM or MDX with a plugin
• [x] [ASTs][section-syntax-tree] — inspecting and changing content made easy
• [x] [popular][] — world’s most popular markdown parser
• [x] [plugins][section-plugins] — 150+ plugins you can pick and choose from

Intro

remark is an ecosystem of plugins that work with markdown as structured data, specifically ASTs (abstract syntax trees). ASTs make it easy for programs to deal with markdown. We call those programs plugins. Plugins inspect and change trees. You can use the many existing plugins or you can make your own.

• to learn markdown, see this [cheatsheet and tutorial][commonmark-help]
• for more about us, see [unifiedjs.com][unifiedjs]
• for questions, see [support][health-support]
• to help, see [contribute][section-contribute] or [sponsor][section-sponsor] below

Contents

• What is this?
• When should I use this?
• Plugins
• Examples
  • Example: turning markdown into HTML
  • Example: support for GFM and frontmatter
  • Example: checking markdown
  • Example: checking and formatting markdown on the CLI
• Syntax
• Syntax tree
• Types
• Compatibility
• Security
• Contribute
• Sponsor
• License

What is this?

With this project and a plugin, you can turn this markdown:

# Hello, *Mercury*!

…into the following HTML:

<h1>Hello, <em>Mercury</em>!</h1>

<details><summary>Show example code</summary>

import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'

const file = await unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process('# Hello, *Mercury*!')

console.log(String(file)) // => '<h1>Hello, <em>Mercury</em>!</h1>'

</details>

With another plugin, you can turn this markdown:

# Hi, Saturn!

…into the following markdown:

## Hi, Saturn!

<details><summary>Show example code</summary>

/**
 * @import {Root} from 'mdast'
 */

import remarkParse from 'remark-parse'
import remarkStringify from 'remark-stringify'
import {unified} from 'unified'
import {visit} from 'unist-util-visit'

const file = await unified()
  .use(remarkParse)
  .use(myRemarkPluginToIncreaseHeadings)
  .use(remarkStringify)
  .process('# Hi, Saturn!')

console.log(String(file)) // => '## Hi, Saturn!'

function myRemarkPluginToIncreaseHeadings() {
  /**
   * @param {Root} tree
   */
  return function (tree) {
    visit(tree, function (node) {
      if (node.type === 'heading') {
        node.depth++
      }
    })
  }
}

</details>

You can use remark for many different things. [unified][github-unified] is the core project that transforms content with ASTs. remark adds support for markdown to unified. [mdast][github-mdast] is the markdown AST that remark uses.

This GitHub repository is a monorepo that contains the following packages:

• [remark-parse][github-remark-parse] — plugin to take markdown as input and turn it into a syntax tree (mdast)
• [remark-stringify][github-remark-stringify] — plugin to take a syntax tree (mdast) and turn it into markdown as output
• [remark][github-remark-core] — unified, remark-parse, and remark-stringify, useful when input and output are markdown
• [remark-cli][github-remark-cli] — CLI around remark to inspect and format markdown in scripts

When should I use this?

Depending on the input you have and output you want, you can use different parts of remark. If the input is markdown, you can use remark-parse with unified. If the output is markdown, you can use remark-stringify with unified. If both the input and output are markdown, you can use remark on its own. When you want to inspect and format markdown files in a project, you can use remark-cli.

If you just want to turn markdown into HTML (with maybe a few extensions), we recommend [micromark][github-micromark] instead.

If you don’t use plugins and want to deal with syntax trees manually, you can use [mdast-util-from-markdown][github-mdast-util-from-markdown] and [mdast-util-to-markdown][github-mdast-util-to-markdown].

Plugins

remark plugins deal with markdown. Some popular examples are:

• [remark-gfm][github-remark-gfm] — add support for GFM (GitHub flavored markdown)
• [remark-lint][github-remark-lint] — inspect markdown and warn about inconsistencies
• [remark-toc][github-remark-toc] — generate a table of contents
• [remark-rehype][github-remark-rehype] — turn markdown into HTML

These plugins are exemplary because what they do and how they do it is quite different, respectively to extend markdown syntax, inspect trees, change trees, and transform to other syntax trees.

You can choose from the 150+ plugins that already exist. Here are three good ways to find plugins:

• [awesome-remark][github-awesome-remark] — selection of the most awesome projects
• [List of plugins][file-list-of-plugins] — list of all plugins
• [remark-plugin topic][github-topic-remark-plugin] — any tagged repo on GitHub

Some plugins are maintained by us here in the @remarkjs organization while others are maintained by folks elsewhere. Anyone can make remark plugins, so as always when choosing whether to include dependencies in your project, make sure to carefully assess the quality of remark plugins too.

Examples

Example: turning markdown into HTML

remark is an ecosystem around markdown. A different ecosystem is for HTML: [rehype][github-rehype]. The following example turns markdown into HTML by combining both ecosystems with [remark-rehype][github-remark-rehype]:

import rehypeSanitize from 'rehype-sanitize'
import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'

const file = await unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeSanitize)
  .use(rehypeStringify)
  .process('# Hello, Neptune!')

console.log(String(file))

Yields:

<h1>Hello, Neptune!</h1>

Example: support for GFM and frontmatter

remark supports CommonMark by default. Non-standard markdown extensions can be enabled with plugins. The following example adds support for GFM (autolink literals, footnotes, strikethrough, tables, tasklists) and frontmatter (YAML):

import rehypeStringify from 'rehype-stringify'
import remarkFrontmatter from 'remark-frontmatter'
import remarkGfm from 'remark-gfm'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'

const value = `---
layout: solar-system
---

# Hi ~~Mars~~Venus!
`

const file = await unified()
  .use(remarkParse)
  .use(remarkFrontmatter)
  .use(remarkGfm)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process(value)

console.log(String(file))

Yields:

<h1>Hi <del>Mars</del>Venus!</h1>

Example: checking markdown

The following example checks that markdown code style is consistent and follows recommended best practices:

import {remark} from 'remark'
import remarkPresetLintConsistent from 'remark-preset-lint-consistent'
import remarkPresetLintRecommended from 'remark-preset-lint-recommended'
import {reporter} from 'vfile-reporter'

const file = await remark()
  .use(remarkPresetLintConsistent)
  .use(remarkPresetLintRecommended)
  .process('1) Hello, _Jupiter_ and *Neptune*!')

console.error(reporter(file))

Yields:

1:2           warning Unexpected ordered list marker `)`, expected `.`                                     ordered-list-marker-style remark-lint
1:25-1:34     warning Unexpected emphasis marker `*`, expected `_`                                         emphasis-marker           remark-lint
  [cause]:
    1:11-1:20 info    Emphasis marker style `'_'` first defined for `'consistent'` here                    emphasis-marker           remark-lint
1:35          warning Unexpected missing final newline character, expected line feed (`\n`) at end of file final-newline             remark-lint

⚠ 3 warnings

Example: checking and formatting markdown on the CLI

The following example checks and formats markdown with remark-cli, which is the CLI (command line interface) of remark that you can use in your terminal. This example assumes you’re in a Node.js package.

First, install the CLI and plugins:

npm install --save-dev remark-cli remark-preset-lint-consistent remark-preset-lint-recommended remark-toc

…then add an npm script in your package.json:

  /* … */
  "scripts": {
    /* … */
    "format": "remark . --output",
    /* … */
  },
  /* … */

💡 Tip: add ESLint and such in the format script too.

The above change adds a format script, which can be run with npm run format. It runs remark on all markdown files (.) and rewrites them (--output). Run ./node_modules/.bin/remark --help for more info on the CLI.

Then, add a remarkConfig to your package.json to configure remark:

  /* … */
  "remarkConfig": {
    "settings": {
      "bullet": "*",