remark

remark is a popular tool that transforms markdown with plugins. These plugi...

Markdown
remarkjs/remarkremark.js.orgremark

README

![remark][logo]

[![Build][build-badge]][build] [![Coverage][coverage-badge]][coverage] [![Downloads][downloads-badge]][downloads] [![Size][size-badge]][size] [![Sponsors][sponsors-badge]][collective] [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat]

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] [popular][] (world’s most popular markdown parser)
  [x] [compliant][syntax] (100% to CommonMark, 100% to GFM with a plugin)
  [x] [plugins][] (150+ plugins you can pick and choose from)
  [x] [ASTs][syntax-tree] (inspecting and changing content made easy)

Intro


remark is a very popular 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][cheat]
  for more about us, see [unifiedjs.com][site]
  for updates, see [Twitter][]
  for questions, see [support][]
  to help, see [contribute][] or [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?


You can use plugins to turn markdown into HTML.
In:

  1. ```markdown
  2. # Hello, *Mercury*!
  3. ```

Out:

  1. ```html
  2. <h1>Hello, <em>Mercury</em>!</h1>
  3. ```

You can use plugins to change markdown.
In:

  1. ```markdown
  2. # Hi, Saturn!
  3. ```

Plugin:

  1. ```js
  2. import {visit} from 'unist-util-visit'

  4. /** @type {import('unified').Plugin<[], import('mdast').Root>} */
  5. function myRemarkPluginToIncreaseHeadings() {
  6.   return (tree) => {
  7.     visit(tree, (node) => {
  8.       if (node.type === 'heading') {
  9.         node.depth++
  10.       }
  11.     })
  12.   }
  13. }
  14. ```

Out:

  1. ```markdown
  2. ## Hi, Saturn!
  3. ```

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

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

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

When should I use this?


If you just want to turn markdown into HTML (with maybe a few extensions),
we recommend [micromark][micromark] instead.
remark can also do that but it focusses on ASTs and providing an interface for
plugins to transform them.

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.

Plugins


remark plugins deal with markdown.
Some popular examples are:

  [remark-gfm][remark-gfm]
    — add support for GFM (GitHub flavored markdown)
  [remark-lint][remark-lint]
    — inspect markdown and warn about inconsistencies
  [remark-toc][remark-toc]
    — generate a table of contents
  [remark-html][remark-html]
    — turn the syntax tree into serialized 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 define other output formats.

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

  [awesome-remark][awesome-remark]
    — selection of the most awesome projects
  [List of plugins][list-of-plugins]
    — list of all plugins
  [remark-plugin topic][topic]
    — 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][].
The following example turns markdown into HTML by combining both ecosystems with
[remark-rehype][remark-rehype]:

  1. ```js
  2. import {unified} from 'unified'
  3. import remarkParse from 'remark-parse'
  4. import remarkRehype from 'remark-rehype'
  5. import rehypeSanitize from 'rehype-sanitize'
  6. import rehypeStringify from 'rehype-stringify'

  8. main()

  10. async function main() {
  11.   const file = await unified()
  12.     .use(remarkParse)
  13.     .use(remarkRehype)
  14.     .use(rehypeSanitize)
  15.     .use(rehypeStringify)
  16.     .process('# Hello, Neptune!')

  18.   console.log(String(file))
  19. }
  20. ```

Yields:

  1. ```html
  2. <h1>Hello, Neptune!</h1>
  3. ```

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):

  1. ```js
  2. import {unified} from 'unified'
  3. import remarkParse from 'remark-parse'
  4. import remarkFrontmatter from 'remark-frontmatter'
  5. import remarkGfm from 'remark-gfm'
  6. import remarkRehype from 'remark-rehype'
  7. import rehypeStringify from 'rehype-stringify'

  9. main()

  11. async function main() {
  12.   const file = await unified()
  13.     .use(remarkParse)
  14.     .use(remarkFrontmatter)
  15.     .use(remarkGfm)
  16.     .use(remarkRehype)
  17.     .use(rehypeStringify)
  18.     .process('---\nlayout: home\n---\n\n# Hi ~~Mars~~Venus!')

  20.   console.log(String(file))
  21. }
  22. ```

Yields:

  1. ```html
  2. <h1>Hi <del>Mars</del>Venus!</h1>
  3. ```

Example: checking markdown


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

  1. ```js
  2. import {reporter} from 'vfile-reporter'
  3. import {remark} from 'remark'
  4. import remarkPresetLintConsistent from 'remark-preset-lint-consistent'
  5. import remarkPresetLintRecommended from 'remark-preset-lint-recommended'

  7. main()

  9. async function main() {
  10.   const file = await remark()
  11.     .use(remarkPresetLintConsistent)
  12.     .use(remarkPresetLintRecommended)
  13.     .process('1) Hello, _Jupiter_ and *Neptune*!')

  15.   console.error(reporter(file))
  16. }
  17. ```

Yields:

  1. ```txt
  2.         1:1  warning  Missing newline character at end of file  final-newline              remark-lint
  3.    1:1-1:35  warning  Marker style should be `.`                ordered-list-marker-style  remark-lint
  4.         1:4  warning  Incorrect list-item indent: add 1 space   list-item-indent           remark-lint
  5.   1:25-1:34  warning  Emphasis should use `_` as a marker       emphasis-marker            remark-lint

  7. ⚠ 4 warnings
  8. ```

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:

  1. ```sh
  2. npm install remark-cli remark-toc remark-preset-lint-consistent remark-preset-lint-recommended --save-dev
  3. ```

Now, add an npm script in your package.json:

  1. ```js
  2.   /* … */
  3.   "scripts": {
  4.     /* … */
  5.     "format": "remark . --output",
  6.     /* … */
  7.   },
  8.   /* … */
  9. ```

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


Observe that 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:

  1. ```js
  2.   /* … */
  3.   "remarkConfig": {
  4.     "settings": {
  5.       "bullet": "*", // Use `*` for list item bullets (default)
  6.       // See for more options.
  7.     },
  8.     "plugins": [
  9.       "remark-preset-lint-consistent", // Check that markdown is consistent.
  10.       "remark-preset-lint-recommended", // Few recommended rules.
  11.       [
  12.         // Generate a table of contents in `## Contents`
  13.         "remark-toc",
  14.         {
  15.           "heading": "contents"
  16.         }
  17.       ]
  18.     ]
  19.   },
  20.   /* … */
  21. ```

👉 Note: you must remove the comments in the above examples when

copy/pasting them, as comments are not supported in package.json files.


Finally, you can run the npm script to check and format markdown files in your
project:

  1. ```sh
  2. npm run format
  3. ```

Syntax


remark follows CommonMark, which standardizes the differences between markdown
implementations, by default.
Some syntax extensions are supported through plugins.

We use [micromark][micromark] for our parsing.
See its documentation for more information on markdown, CommonMark, and
extensions.

Syntax tree


The syntax tree format used in remark is [mdast][].
It represents markdown constructs as JSON objects.
In:

  1. ```markdown
  2. ## Hello *Pluto*!
  3. ```

Out:

  1. ```js
  2. {
  3.   type: 'heading',
  4.   depth: 2,
  5.   children: [
  6.     {type: 'text', value: 'Hello '},
  7.     {type: 'emphasis', children: [{type: 'text', value: 'Pluto'}]}
  8.     {type: 'text', value: '!'}
  9.   ]
  10. }
  11. ```

Types


The remark organization and the unified collective as a whole is fully typed
with [TypeScript][].
Types for mdast are available in [@types/mdast][types-mdast].

For TypeScript to work, it is particularly important to type your plugins
correctly.
We strongly recommend using the Plugin type from unified with its generics
and to use the node types for the syntax trees provided by @types/mdast.

  1. ```js
  2. /**
  3. * @typedef {import('mdast').Root} Root
  4. *
  5. * @typedef Options
  6. *   Configuration (optional).
  7. * @property {boolean} [someField]
  8. *   Some option.
  9. */

  11. // To type options and that the it works with `mdast`:
  12. /** @type {import('unified').Plugin<[Options?], Root>} */
  13. export function myRemarkPluginAcceptingOptions(options) {
  14.   // `options` is `Options?`.
  15.   return function (tree, file) {
  16.     // `tree` is `Root`.
  17.   }
  18. }
  19. ```

Compatibility


Projects maintained by the unified collective are compatible with all maintained
versions of Node.js.
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
Our projects sometimes work with older versions, but this is not guaranteed.

Security


As markdown can be turned into HTML and improper use of HTML can open you up to
[cross-site scripting (XSS)][xss] attacks, use of remark can be unsafe.
When going to HTML, you will likely combine remark with [rehype][], in which
case you should use [rehype-sanitize][rehype-sanitize].

Use of remark plugins could also open you up to other attacks.
Carefully assess each plugin and the risks involved in using them.

For info on how to submit a report, see our [security policy][security].

Contribute


See [contributing.md][contributing] in [remarkjs/.github][health] for ways
to get started.
See [support.md][support] for ways to get help.
Join us in [Discussions][chat] to chat with the community and contributors.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

Sponsor


Support this effort and give back by sponsoring on [OpenCollective][collective]!

Vercel

 Motif

 HashiCorp

 GitBook

 Gatsby

Netlify

 Coinbase

 ThemeIsle

 Expo

 Boost Note

 Holloway


You?


License


MIT © Titus Wormer


[logo]: https://raw.githubusercontent.com/remarkjs/remark/1f338e72/logo.svg?sanitize=true

[build-badge]: https://github.com/remarkjs/remark/workflows/main/badge.svg

[build]: https://github.com/remarkjs/remark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/remarkjs/remark.svg

[coverage]: https://codecov.io/github/remarkjs/remark

[downloads-badge]: https://img.shields.io/npm/dm/remark.svg

[downloads]: https://www.npmjs.com/package/remark

[size-badge]: https://img.shields.io/bundlephobia/minzip/remark.svg

[size]: https://bundlephobia.com/result?p=remark

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/remarkjs/remark/discussions

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[security]: https://github.com/remarkjs/.github/blob/main/security.md

[health]: https://github.com/remarkjs/.github

[contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md

[support]: https://github.com/remarkjs/.github/blob/main/support.md

[coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md

[collective]: https://opencollective.com/unified

[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[typescript]: https://www.typescriptlang.org

[cheat]: https://commonmark.org/help/

[twitter]: https://twitter.com/unifiedjs

[site]: https://unifiedjs.com

[topic]: https://github.com/topics/remark-plugin

[popular]: https://www.npmtrends.com/remark-parse-vs-marked-vs-micromark-vs-markdown-it

[types-mdast]: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/mdast

[unified]: https://github.com/unifiedjs/unified

[remark-gfm]: https://github.com/remarkjs/remark-gfm

[remark-toc]: https://github.com/remarkjs/remark-toc

[remark-rehype]: https://github.com/remarkjs/remark-rehype

[remark-html]: https://github.com/remarkjs/remark-html

[remark-lint]: https://github.com/remarkjs/remark-lint

[awesome-remark]: https://github.com/remarkjs/awesome-remark

[rehype]: https://github.com/rehypejs/rehype

[rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize

[mdast]: https://github.com/syntax-tree/mdast

[micromark]: https://github.com/micromark/micromark

[remark-parse]: packages/remark-parse/

[remark-stringify]: packages/remark-stringify/

[remark-core]: packages/remark/

[remark-cli]: packages/remark-cli/

[list-of-plugins]: doc/plugins.md#list-of-plugins

[syntax]: #syntax

[syntax-tree]: #syntax-tree

[plugins]: #plugins

[contribute]: #contribute

[sponsor]: #sponsor