Doc/Getting Started

Getting started

See [the monorepo readme][remark] for what the remark ecosystem is and examples
of how to get started.

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

---

Doc/Plugins

![remark][file-logo]

Plugins

remark is a tool that transforms markdown with plugins.
See [the monorepo readme][github-remark] for info on what the remark ecosystem
is.
This page lists existing plugins.

* List of plugins
* List of utilities
* Use plugins
* Create plugins

List of plugins

For the most awesome projects in the ecosystem,
see [remarkjs/awesome-remark][github-remark-awesome-remark].
More plugins can be found on GitHub tagged with the
[remark-plugin topic][github-topic-remark-plugin].

👉 Note:

some plugins don’t work with recent versions of remark due to changes in its

underlying parser (micromark).

Plugins that are up to date or unaffected are marked with 🟢 while plugins

that are currently broken are marked with ⚠️.

💡 Tip:

remark plugins work with markdown and rehype plugins work with HTML.

See [§ List of plugins in rehypejs/rehype][github-rehype-plugins] for more

plugins.

The list of plugins:

* remark-a11y-emoji
— accessible emoji
* ⚠️ remark-abbr
— new syntax for abbreviations (new node type, rehype compatible)
* ⚠️ remark-admonitions
— new syntax for admonitions
(👉 note: [remark-directive][github-remark-directive] is similar and up
to date)
* ⚠️ remark-align
— new syntax to align text or blocks (new node types, rehype
compatible)
* 🟢 remark-api
— generate an API section
* ⚠️ remark-attr
— new syntax to add attributes to markdown
* 🟢 remark-behead
— increase or decrease heading depth
* 🟢 remark-breaks
– hard breaks w/o needing spaces (like on issues)
* 🟢 remark-capitalize
– transform all titles w/ title.sh
* 🟢 remark-capitalize-headings
– selectively capitalize headings
(👉 note: alternative to remark-capitalize)
* 🟢 remark-cite
– new syntax for Pandoc-style citations
* 🟢 remark-cjk-friendly
– recognize emphasis in CJK languages more reliably
* 🟢 remark-cjk-friendly-gfm-strikethrough
– recognize GFM strikethrough in CJK languages more reliably
* 🟢 remark-cloudinary-docusaurus
– allows Docusaurus to use Cloudinary to serve optimised images
* 🟢 remark-code-blocks
— select and store code blocks
* 🟢 remark-code-extra
— add to or transform the HTML output of code blocks (rehype compatible)
* 🟢 remark-code-frontmatter
— extract frontmatter from code blocks
* 🟢 remark-code-import
— populate code blocks from files
* 🟢 remark-code-screenshot
– turn code blocks into carbon.now.sh screenshots
* 🟢 remark-code-title
— add titles to code blocks
* 🟢 remark-codesandbox
– create CodeSandbox from code blocks
* 🟢 remark-collapse
— make a section collapsible
* 🟢 remark-comment-config
— configure remark w/ comments
* ⚠️ remark-comments
— new syntax to ignore things
* ⚠️ remark-container
— new syntax for containers
(👉 note: [remark-directive][github-remark-directive] is similar and up
to date)
* ⚠️ remark-containers
— new syntax for containers
(👉 note: [remark-directive][github-remark-directive] is similar and up
to date)
* 🟢 remark-contributors
— add a table of contributors
* 🟢 remark-copy-linked-files
— find and copy files linked files to a destination directory
* 🟢 remark-corebc
— transforms Core Blockchain notations into markdown links
* 🟢 remark-corepass
— transform CorePass notations into markdown links
* ⚠️ remark-custom-blocks
— new syntax for custom blocks (new node types, rehype compatible)
(👉 note: [remark-directive][github-remark-directive] is similar and up
to date)
* 🟢 remark-custom-header-id
— add custom ID attribute to headers ({#some-id})
* 🟢 remark-definition-list
— support definition lists
* 🟢 remark-defsplit
— change links and images to references w/ separate definitions
* ⚠️ remark-disable-tokenizers
— turn some or all remark’s tokenizers on or off
* 🟢 remark-directive
— new syntax for directives (generic extensions)
* 🟢 remark-directive-rehype
— turn [directives][github-remark-directive] into HTML custom elements
(rehype compatible)
* 🟢 remark-directive-sugar
— predefined directives for customizable badges, links, video embeds, and more
* 🟢 remark-docx
— compile markdown to docx
* 🟢 @m2d/remark-docx
— compile markdown to docx with support for GFM, tables, html, and more.
* 🟢 remark-dropcap
— fancy and accessible drop caps
* 🟢 remark-embed-images
— embed local images as base64-encoded data URIs
* 🟢 remark-emoji
— transform Gemoji short-codes to emoji
* 🟢 remark-extended-table
— extended table syntax allowing colspan / rowspan
* 🟢 remark-extract-frontmatter
— store front matter in vfiles
* 🟢 remark-fediverse-user
— transform Fediverse user notations into markdown links
* 🟢 remark-first-heading
— change the first heading in a document
* 🟢 remark-fix-guillemets
— support ASCII guillements (<<, >>) mapping them to HTML
* 🟢 remark-flexible-code-titles
— add titles or/and containers for code blocks with customizable attributes
* 🟢 remark-flexible-containers
— add custom/flexible containers with customizable properties
* 🟢 remark-flexible-markers
— add custom/flexible mark element with customizable properties
* 🟢 remark-flexible-paragraphs
— add custom/flexible paragraphs with customizable properties
* 🟢 remark-flexible-toc
— expose the table of contents (toc) via Vfile.data or an option reference
* 🟢 remark-footnotes-extra
— add footnotes via short syntax
* 🟢 remark-frontmatter
– support frontmatter (yaml, toml, and more)
* 🟢 remark-gemoji
— better support for Gemoji shortcodes
* ⚠️ remark-generic-extensions
— new syntax for the CommonMark generic directive extension
(👉 note: [remark-directive][github-remark-directive] is similar and up
to date)
* 🟢 remark-gfm
— support GFM (autolink literals, footnotes, strikethrough, tables,
tasklists)
* 🟢 remark-git-contributors
— add a table of contributors based on Git history, options, and more
* 🟢 remark-github
— autolink references to commits, issues, pull-requests, and users
* 🟢 remark-github-admonitions-to-directives
— convert GitHub’s blockquote-based admonitions syntax to directives syntax
* 🟢 remark-github-beta-blockquote-admonitions
— GitHub beta blockquote-based admonitions
* 🟢 remark-github-blockquote-alert
— remark plugin to add support for GitHub Alert
* ⚠️ remark-grid-tables
— new syntax to describe tables (rehype compatible)
* 🟢 @adobe/remark-grid-tables
— pandoc compatible grid-table syntax
* 🟢 remark-heading-id
— custom heading id support {#custom-id}
* 🟢 remark-heading-gap
— serialize w/ more blank lines between headings
* 🟢 @vcarl/remark-headings
— extract a list of headings as data
* 🟢 remark-hexo
— renders Hexo tags
* 🟢 remark-highlight.js
— highlight code blocks w/
highlight.js
(rehype compatible)
* 🟢 remark-hint
— add hints/tips/warnings to markdown
* 🟢 remark-html
— serialize markdown as HTML
* ⚠️ remark-iframes
— new syntax to create iframes (new node type, rehype compatible)
* 🟢 remark-ignore
— use comments to exclude nodes from transformation
* 🟢 remark-images
— add an improved image syntax
* 🟢 remark-img-links
— prefix relative image paths with an absolute URL
* 🟢 @it-service-npm/remark-include
— add ::include{file=path.md} statements to compose markdown files together
* 🟢 remark-inline-links
— change references and definitions to links and images
* 🟢 remark-ins
— add ins element for inserted texts opposite to deleted texts
* 🟢 remark-join-cjk-lines
— remove extra space between CJK Characters.
* ⚠️ remark-kbd
— new syntax for keyboard keys (new node type, rehype compatible)
* ⚠️ remark-kbd-plus
— new syntax for keyboard keys w/ plusses (new node type, rehype
compatible)
* 🟢 remark-license
— add a license section
* 🟢 remark-link-rewrite
— customize link URLs dynamically
* 🟢 remark-linkify-regex
— change text matching a regex to links
* 🟢 remark-lint
— check markdown code style
* 🟢 remark-man
— serialize markdown as man pages (roff)
* 🟢 remark-math
— new syntax for math (new node types, rehype compatible)
* 🟢 remark-mdx
— support MDX (JSX, expressions, ESM)
* 🟢 remark-mentions
— replace @ mentions with links
* 🟢 remark-merge-data
— merge globally defined data with data declared across code blocks
* 🟢 remark-mermaidjs
— transform mermaid code blocks into inline SVGs
* 🟢 remark-message-control
— turn some or all messages on or off
* 🟢 remark-normalize-headings
— make sure at most one top-level heading exists
* 🟢 remark-numbered-footnote-labels
— label footnotes w/ numbers
* 🟢 @agentofuser/remark-oembed
— transform URLs for youtube, twitter, etc. embeds
* 🟢 remark-oembed
— transform URLs surrounded by newlines into asynchronously loading
embeds
* 🟢 remark-package-dependencies
— inject your dependencies
* ⚠️ remark-parse-yaml
— parse YAML nodes and expose their value as parsedValue
* 🟢 remark-pdf
— compile markdown to pdf
* ⚠️ remark-ping
— new syntax for mentions w/ configurable existence check (new node
type, rehype compatible)
* 🟢 remark-plugin-autonbsp
— replace whitespace with non-breaking spaces
to avoid hanging articles, prepositions and digits
* 🟢 remark-prepend-url
— prepend an absolute url to relative links
* 🟢 remark-prettier
— check and format markdown using Prettier
* 🟢 remark-prism
— highlight code blocks w/ Prism (supporting most
Prism plugins)
* 🟢 @handlewithcare/remark-prosemirror
— compile markdown to ProseMirror documents
* ⚠️ remark-redact
— new syntax to conceal text matching a regex
* 🟢 remark-redactable
— write plugins to redact content from a markdown document,
then restore it later
* 🟢 remark-refer-plantuml
— automatically transform PlantUML code into referenced embeddable image URLs
* 🟢 remark-reference-links
— transform links and images into references and definitions
* 🟢 remark-rehype
— transform to rehype
* 🟢 remark-relative-links
— change absolute URLs to relative ones
* 🟢 remark-remove-comments
— remove HTML comments from the processed output
* 🟢 remark-remove-unused-definitions
— remove unused reference-style link definitions
* 🟢 remark-remove-url-trailing-slash
— remove trailing slashes from the ends of all URL paths
* 🟢 remark-renumber-references
— renumber numeric reference-style link ids contiguously starting from 1
* 🟢 remark-retext
— transform to retext
* 🟢 remark-ruby
— new syntax for ruby (furigana)
* 🟢 remark-sectionize
— wrap headings and subsequent content in section tags (new node type,
rehype compatible)
* ⚠️ remark-shortcodes
— new syntax for Wordpress- and Hugo-like shortcodes (new node type)
(👉 note: [remark-directive][github-remark-directive] is similar and up
to date)
* 🟢 remark-simple-plantuml
— turn PlantUML code blocks to images
* 🟢 remark-slate
— compile markdown to Slate nodes
* 🟢 remark-slate-transformer
— compile markdown to
Slate nodes
and Slate nodes to markdown
* 🟢 remark-smartypants
— SmartyPants
* 🟢 remark-smcat
— state machine cat
* 🟢 remark-sort-definitions
— reorder reference-style link definitions
* 🟢 remark-sources
— insert source code
* 🟢 remark-strip-badges
— remove badges (such as shields.io)
* 🟢 remark-strip-html
— remove HTML
* 🟢 remark-squeeze-paragraphs
— remove empty paragraphs
* ⚠️ remark-sub-super
— new syntax for super- and subscript (new node types, rehype
compatible)
* ⚠️ remark-terms
— new customizable syntax for special terms and phrases
* 🟢 remark-textr
— transform text w/ Textr
* 🟢 remark-tight-comments
— selectively remove newlines around comments
* 🟢 remark-title
— check and add the document title
* 🟢 remark-toc
— add a table of contents
* 🟢 remark-torchlight
— syntax highlighting powered by torchlight.dev
* 🟢 remark-tree-sitter
— highlight code blocks in markdown files using
Tree-sitter
(rehype compatible)
* 🟢 remark-truncate-links
— truncate/shorten urls not manually named
* 🟢 remark-twemoji
— turn emoji into Twemoji
* 🟢 remark-typedoc-symbol-links
— turn Typedoc symbol link expressions into markdown links
* 🟢 remark-typescript
— turn TypeScript code to JavaScript
* 🟢 remark-typograf
— transform text w/ Typograf
* 🟢 remark-unlink
— remove all links, references, and definitions
* 🟢 remark-usage
— add a usage example
* 🟢 remark-utf8
— turn bolds, italics, and code into UTF 8 special characters
* 🟢 remark-validate-links
— check links to headings and files
* ⚠️ remark-variables
— new syntax for variables
* 🟢 remark-vdom
— compile markdown to VDOM
* 🟢 remark-wiki-link
— new syntax for wiki links (rehype compatible)
* 🟢 remark-yaml-config
— configure remark w/ YAML

List of utilities

For things that work with the syntax tree used in remark for markdown,
see [§ List of utilities in syntax-tree/mdast][github-mdast-utilities].
For tools that work with mdast and other syntax trees,
see [§ List of utilities in syntax-tree/unist][github-unist-utilities].
For tools that work with the virtual file format used in remark,
see [§ List of utilities in vfile/vfile][github-vfile-utilities].

Use plugins

To use a plugin programmatically (from JavaScript),
call the [use()][github-unified-use] method.
To use plugin with remark-cli (from the terminal),
pass a [--use flag][github-unified-args-use] or
specify it in a
[configuration file][github-unified-engine-config-files].

Create plugins

To create a plugin,
first read up on what they are in
[§ Plugin in unifiedjs/unified][github-unified-plugin].
After that read
[§ Create a remark plugin on unifiedjs.com][unifiedjs-create-a-plugin]
for a practical introduction.
Finally take one of the existing plugins,
which looks similar to what you’re about to make,
and work from there.
If you get stuck,
[discussions][health-discussions] is a good place to get help.

You should pick a name prefixed by remark- (such as remark-lint).
Do not use the remark- prefix if the thing you create doesn’t work with
remark().use():
it isn’t a “plugin” and will confuse users.
If it works with mdast use mdast-util-.
If it works with any unist tree use unist-util-.
If it works with virtual files use vfile-.

Use default exports to expose plugins from your packages.
Add remark-plugin keywords in package.json.
Add a remark-plugin topic to your repo on GitHub.
Create a pull request to add the plugin here on this page!

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

[github-mdast-utilities]: https://github.com/syntax-tree/mdast#list-of-utilities

[github-rehype-plugins]: https://github.com/rehypejs/rehype/blob/main/doc/plugins.md#list-of-plugins

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

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

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

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

[github-unified-args-use]: https://github.com/unifiedjs/unified-args#--use-plugin

[github-unified-engine-config-files]: https://github.com/unifiedjs/unified-engine#config-files

[github-unified-plugin]: https://github.com/unifiedjs/unified#plugin

[github-unified-use]: https://github.com/unifiedjs/unified#processoruseplugin-options

[github-unist-utilities]: https://github.com/syntax-tree/unist#unist-utilities

[github-vfile-utilities]: https://github.com/vfile/vfile#list-of-utilities

[health-discussions]: https://github.com/remarkjs/remark/discussions

[unifiedjs-create-a-plugin]: https://unifiedjs.com/learn/guide/create-a-remark-plugin/

---

Doc/Products

Products

See [awesome remark][awesome] for the products using remark.

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

---

Changelog

See [GitHub Releases][releases] for the changelog.

[releases]: https://github.com/remarkjs/remark/releases

---

Readme

![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

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

markdown

Hello, Mercury!

…into the following HTML:

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:

markdown

Hi, Saturn!

…into the following markdown:

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:

html

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

html

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

text

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": "", // Use  for list item bullets (default)
      // See <https://github.com/remarkjs/remark/tree/main/packages/remark-stringify> for more options.
    },
    "plugins": [
      "remark-preset-lint-consistent", // Check that markdown is consistent.
      "remark-preset-lint-recommended", // Few recommended rules.
      [
        // Generate a table of contents in ## Contents
        "remark-toc",
        {
          "heading": "contents"
        }
      ]
    ]
  },
  / … /

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

npm run format

Syntax

Markdown is parsed and serialized according to CommonMark.
Other plugins can add support for syntax extensions.

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

Syntax tree

The syntax tree used in remark is [mdast][github-mdast].
It represents markdown constructs as JSON objects.

This markdown:

markdown

Hello Pluto!

…yields the following tree (positional info remove for brevity):

{
  type: 'heading',
  depth: 2,
  children: [
    {type: 'text', value: 'Hello '},
    {type: 'emphasis', children: [{type: 'text', value: 'Pluto'}]}
    {type: 'text', value: '!'}
  ]
}

Types

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

For TypeScript to work,
it is important to type your plugins.
For example:

/
 * @import {Root} from 'mdast'
 * @import {VFile} from 'vfile'
 */
/
 * @typedef Options
 *   Configuration.
 * @property {boolean | null | undefined} [someField]
 *   Some option (optional).
 *//
 * My plugin.
 *
 * @param {Options | null | undefined} [options]
 *   Configuration (optional).
 * @returns
 *   Transform.
 */
export function myRemarkPluginAcceptingOptions(options) {
  /
   * Transform.
   *
   * @param {Root} tree
   *   Tree.
   * @param {VFile} file
   *   File
   * @returns {undefined}
   *   Nothing.
   */
  return function (tree, file) {
    // Do things.
  }
}

Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release,
we drop support for unmaintained versions of Node.
This means we try to keep the current release line compatible with Node.js 16.

Security

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

Another security aspect is DDoS attacks.
An attacker could cause a crash or slow down with big files.
Crashes can also originate from smaller payloads,
often when thousands of things (such as lists or links) are opened.
It is wise to cap the accepted size of input
(500kb can hold a big book)
and to process content in a different thread or worker so that it can be
stopped when needed.

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][health-security].

Contribute

See [contributing.md][health-contributing] in [remarkjs/.github][health]
for ways to get started.
See [support.md][health-support] for ways to get help.

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

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

<table>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://vercel.com">Vercel</a> 
<a href="https://vercel.com"><img src="https://avatars1.githubusercontent.com/u/14985020?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://motif.land">Motif</a> 
<a href="https://motif.land"><img src="https://avatars1.githubusercontent.com/u/74457950?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.hashicorp.com">HashiCorp</a> 
<a href="https://www.hashicorp.com"><img src="https://avatars1.githubusercontent.com/u/761456?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.gitbook.com">GitBook</a> 
<a href="https://www.gitbook.com"><img src="https://avatars1.githubusercontent.com/u/7111340?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.gatsbyjs.org">Gatsby</a> 
<a href="https://www.gatsbyjs.org"><img src="https://avatars1.githubusercontent.com/u/12551863?s=256&v=4" width="128"></a>
</td>
</tr>
<tr valign="middle">
</tr>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.netlify.com">Netlify</a> 

<a href="https://www.netlify.com"><img src="https://images.opencollective.com/netlify/4087de2/logo/256.png" width="128"></a>
</td>
<td width="10%" align="center">
<a href="https://www.coinbase.com">Coinbase</a> 
<a href="https://www.coinbase.com"><img src="https://avatars1.githubusercontent.com/u/1885080?s=256&v=4" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://themeisle.com">ThemeIsle</a> 
<a href="https://themeisle.com"><img src="https://avatars1.githubusercontent.com/u/58979018?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://expo.io">Expo</a> 
<a href="https://expo.io"><img src="https://avatars1.githubusercontent.com/u/12504344?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://boostnote.io">Boost Note</a> 
<a href="https://boostnote.io"><img src="https://images.opencollective.com/boosthub/6318083/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://markdown.space">Markdown Space</a> 
<a href="https://markdown.space"><img src="https://images.opencollective.com/markdown-space/e1038ed/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://www.holloway.com">Holloway</a> 
<a href="https://www.holloway.com"><img src="https://avatars1.githubusercontent.com/u/35904294?s=128&v=4" width="64"></a>
</td>
<td width="10%"></td>
<td width="10%"></td>
</tr>
<tr valign="middle">
<td width="100%" align="center" colspan="8">
 
<a href="https://opencollective.com/unified">You?</a>
 
</td>
</tr>
</table>

License

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

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

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

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

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

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

[badge-size-image]: https://img.shields.io/bundlejs/size/remark

[badge-size-url]: https://bundlejs.com/?q=remark

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

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

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

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

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

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

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

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

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

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

[github-remark-cli]: https://github.com/remarkjs/remark/tree/main/packages/remark-cli

[github-remark-core]: https://github.com/remarkjs/remark/tree/main/packages/remark

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

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

[github-remark-parse]: https://github.com/remarkjs/remark/tree/main/packages/remark-parse

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

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

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

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

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

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

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

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

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

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

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

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

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

[section-contribute]: #contribute

[section-plugins]: #plugins

[section-sponsor]: #sponsor

[section-syntax]: #syntax

[section-syntax-tree]: #syntax-tree

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

[unifiedjs]: https://unifiedjs.com

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

---

remark

Doc/Getting Started

Getting started

Doc/Plugins

Plugins

Contents

List of plugins

List of utilities

Use plugins

Create plugins

Doc/Products

Products

Changelog

Changelog

Readme

![remark][file-logo]

Feature highlights

Intro

Contents

What is this?

Hello, Mercury!

Hi, Saturn!

Hi, Saturn!

When should I use this?

Plugins

Examples

Example: turning markdown into HTML

Example: support for GFM and frontmatter

`Hi MarsVenus!`

Example: checking markdown

Example: checking and formatting markdown on the CLI

Syntax

Syntax tree

Hello Pluto!

Types

Compatibility

Security

Contribute

License

Table of Contents

Doc/Getting Started Copy Section

Getting started

Doc/Plugins Copy Section

Plugins

Contents Copy Chapter

List of plugins Copy Chapter

List of utilities Copy Chapter

Use plugins Copy Chapter

Create plugins Copy Chapter

Doc/Products Copy Section

Products

Changelog Copy Section

Changelog

Readme Copy Section

![remark][file-logo]

Feature highlights Copy Chapter

Intro Copy Chapter

Contents Copy Chapter

What is this? Copy Chapter

Hello, Mercury!

Hi, Saturn!

Hi, Saturn! Copy Chapter

When should I use this? Copy Chapter

Plugins Copy Chapter

Examples Copy Chapter

Example: turning markdown into HTML Copy Section

Example: support for GFM and frontmatter Copy Section

Hi ~~Mars~~Venus!

Example: checking markdown Copy Section

Example: checking and formatting markdown on the CLI Copy Section

Syntax Copy Chapter

Syntax tree Copy Chapter

Hello Pluto! Copy Chapter

Types Copy Chapter

Compatibility Copy Chapter

Security Copy Chapter

Contribute Copy Chapter

Sponsor Copy Chapter

License Copy Chapter

Explore Related Technologies & Topics

Doc/Getting Started

Doc/Plugins

Contents

List of plugins

List of utilities

Use plugins

Create plugins

Doc/Products

Changelog

Readme

Feature highlights

Intro

Contents

What is this?

Hi, Saturn!

When should I use this?

Plugins

Examples

Example: turning markdown into HTML

Example: support for GFM and frontmatter

`Hi MarsVenus!`

Example: checking markdown

Example: checking and formatting markdown on the CLI

Syntax

Syntax tree

Hello Pluto!

Types

Compatibility

Security

Contribute

Sponsor

License