### 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.
## Contents
* [List of plugins](#list-of-plugins)
* [List of utilities](#list-of-utilities)
* [Use plugins](#use-plugins)
* [Create 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`](https://github.com/florianeckerstorfer/remark-a11y-emoji)
β accessible emoji
* β οΈ [`remark-abbr`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-abbr#readme)
β new syntax for abbreviations (new node type, rehype compatible)
* β οΈ [`remark-admonitions`](https://github.com/elviswolcott/remark-admonitions)
β new syntax for admonitions
(π **note**: [`remark-directive`][github-remark-directive] is similar and up
to date)
* β οΈ [`remark-align`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-align#readme)
β new syntax to align text or blocks (new node types, rehype
compatible)
* π’ [`remark-api`](https://github.com/wooorm/remark-api)
β generate an API section
* β οΈ [`remark-attr`](https://github.com/arobase-che/remark-attr)
β new syntax to add attributes to markdown
* π’ [`remark-behead`](https://github.com/mrzmmr/remark-behead)
β increase or decrease heading depth
* π’ [`remark-breaks`](https://github.com/remarkjs/remark-breaks)
β hard breaks w/o needing spaces (like on issues)
* π’ [`remark-capitalize`](https://github.com/zeit/remark-capitalize)
β transform all titles w/ [`title.sh`](https://github.com/zeit/title)
* π’ [`remark-capitalize-headings`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-capitalize-headings)
β selectively capitalize headings
(π **note**: alternative to [`remark-capitalize`](https://github.com/zeit/remark-capitalize))
* π’ [`remark-cite`](https://github.com/benrbray/remark-cite)
β new syntax for Pandoc-style citations
* π’ [`remark-cjk-friendly`](https://github.com/tats-u/markdown-cjk-friendly/tree/main/packages/remark-cjk-friendly)
β recognize emphasis in CJK languages ββmore reliably
* π’ [`remark-cjk-friendly-gfm-strikethrough`](https://github.com/tats-u/markdown-cjk-friendly/tree/main/packages/remark-cjk-friendly-gfm-strikethrough)
β recognize GFM strikethrough in CJK languages ββmore reliably
* π’ [`remark-cloudinary-docusaurus`](https://github.com/johnnyreilly/remark-cloudinary-docusaurus)
β allows Docusaurus to use Cloudinary to serve optimised images
* π’ [`remark-code-blocks`](https://github.com/mrzmmr/remark-code-blocks)
β select and store code blocks
* π’ [`remark-code-extra`](https://github.com/samlanning/remark-code-extra)
β add to or transform the HTML output of code blocks (rehype compatible)
* π’ [`remark-code-frontmatter`](https://github.com/samlanning/remark-code-frontmatter)
β extract frontmatter from code blocks
* π’ [`remark-code-import`](https://github.com/kevin940726/remark-code-import)
β populate code blocks from files
* π’ [`remark-code-screenshot`](https://github.com/Swizec/remark-code-screenshot)
β turn code blocks into `carbon.now.sh` screenshots
* π’ [`remark-code-title`](https://github.com/kevinzunigacuellar/remark-code-title)
β add titles to code blocks
* π’ [`remark-codesandbox`](https://github.com/kevin940726/remark-codesandbox)
β create CodeSandbox from code blocks
* π’ [`remark-collapse`](https://github.com/Rokt33r/remark-collapse)
β make a section collapsible
* π’ [`remark-comment-config`](https://github.com/remarkjs/remark-comment-config)
β configure remark w/ comments
* β οΈ [`remark-comments`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-comments#readme)
β new syntax to ignore things
* β οΈ [`remark-container`](https://github.com/zWingz/remark-container)
β new syntax for containers
(π **note**: [`remark-directive`][github-remark-directive] is similar and up
to date)
* β οΈ [`remark-containers`](https://github.com/Nevenall/remark-containers)
β new syntax for containers
(π **note**: [`remark-directive`][github-remark-directive] is similar and up
to date)
* π’ [`remark-contributors`](https://github.com/remarkjs/remark-contributors)
β add a table of contributors
* π’ [`remark-copy-linked-files`](https://github.com/sergioramos/remark-copy-linked-files)
β find and copy files linked files to a destination directory
* π’ [`remark-corebc`](https://github.com/bchainhub/remark-corebc)
β transforms Core Blockchain notations into markdown links
* π’ [`remark-corepass`](https://github.com/bchainhub/remark-corepass)
β transform CorePass notations into markdown links
* β οΈ [`remark-custom-blocks`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-custom-blocks#readme)
β 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`](https://github.com/sindresorhus/remark-custom-header-id)
β add custom ID attribute to headers (`{#some-id}`)
* π’ [`remark-definition-list`](https://github.com/wataru-chocola/remark-definition-list)
β support definition lists
* π’ [`remark-defsplit`](https://github.com/remarkjs/remark-defsplit)
β change links and images to references w/ separate definitions
* β οΈ [`remark-disable-tokenizers`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-disable-tokenizers#readme)
β turn some or all remarkβs tokenizers on or off
* π’ [`remark-directive`](https://github.com/remarkjs/remark-directive)
β new syntax for directives (generic extensions)
* π’ [`remark-directive-rehype`](https://github.com/IGassmann/remark-directive-rehype)
β turn [directives][github-remark-directive] into HTML custom elements
(rehype compatible)
* π’ [`remark-directive-sugar`](https://github.com/lin-stephanie/remark-directive-sugar)
β predefined directives for customizable badges, links, video embeds, and more
* π’ [`remark-docx`](https://github.com/inokawa/remark-docx)
β compile markdown to docx
* π’ [`@m2d/remark-docx`](https://github.com/md2docx/remark-docx)
β compile markdown to docx with support for GFM, tables, html, and more.
* π’ [`remark-dropcap`](https://github.com/brev/remark-dropcap)
β fancy and accessible drop caps
* π’ [`remark-embed-images`](https://github.com/remarkjs/remark-embed-images)
β embed local images as base64-encoded data URIs
* π’ [`remark-emoji`](https://github.com/rhysd/remark-emoji)
β transform Gemoji short-codes to emoji
* π’ [`remark-extended-table`](https://github.com/wataru-chocola/remark-extended-table)
β extended table syntax allowing colspan / rowspan
* π’ [`remark-extract-frontmatter`](https://github.com/mrzmmr/remark-extract-frontmatter)
β store front matter in vfiles
* π’ [`remark-fediverse-user`](https://github.com/bchainhub/remark-fediverse-user)
β transform Fediverse user notations into markdown links
* π’ [`remark-first-heading`](https://github.com/laat/remark-first-heading)
β change the first heading in a document
* π’ [`remark-fix-guillemets`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-fix-guillemets#readme)
β support ASCII guillements (`<<`, `>>`) mapping them to HTML
* π’ [`remark-flexible-code-titles`](https://github.com/ipikuka/remark-flexible-code-titles)
β add titles or/and containers for code blocks with customizable attributes
* π’ [`remark-flexible-containers`](https://github.com/ipikuka/remark-flexible-containers)
β add custom/flexible containers with customizable properties
* π’ [`remark-flexible-markers`](https://github.com/ipikuka/remark-flexible-markers)
β add custom/flexible mark element with customizable properties
* π’ [`remark-flexible-paragraphs`](https://github.com/ipikuka/remark-flexible-paragraphs)
β add custom/flexible paragraphs with customizable properties
* π’ [`remark-flexible-toc`](https://github.com/ipikuka/remark-flexible-toc)
β expose the table of contents (toc) via Vfile.data or an option reference
* π’ [`remark-footnotes-extra`](https://github.com/miaobuao/remark-footnotes-extra)
β add footnotes via short syntax
* π’ [`remark-frontmatter`](https://github.com/remarkjs/remark-frontmatter)
β support frontmatter (yaml, toml, and more)
* π’ [`remark-gemoji`](https://github.com/remarkjs/remark-gemoji)
β better support for Gemoji shortcodes
* β οΈ [`remark-generic-extensions`](https://github.com/medfreeman/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`](https://github.com/remarkjs/remark-gfm)
β support GFM (autolink literals, footnotes, strikethrough, tables,
tasklists)
* π’ [`remark-git-contributors`](https://github.com/remarkjs/remark-git-contributors)
β add a table of contributors based on Git history, options, and more
* π’ [`remark-github`](https://github.com/remarkjs/remark-github)
β autolink references to commits, issues, pull-requests, and users
* π’ [`remark-github-admonitions-to-directives`](https://github.com/incentro-dc/remark-github-admonitions-to-directives)
β convert GitHubβs blockquote-based admonitions syntax to directives syntax
* π’ [`remark-github-beta-blockquote-admonitions`](https://github.com/myl7/remark-github-beta-blockquote-admonitions)
β [GitHub beta blockquote-based admonitions](https://github.com/github/feedback/discussions/16925)
* π’ [`remark-github-blockquote-alert`](https://github.com/jaywcjlove/remark-github-blockquote-alert)
β remark plugin to add support for [GitHub Alert](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)
* β οΈ [`remark-grid-tables`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-grid-tables#readme)
β new syntax to describe tables (rehype compatible)
* π’ [`@adobe/remark-grid-tables`](https://github.com/adobe/remark-gridtables)
β pandoc compatible grid-table syntax
* π’ [`remark-heading-id`](https://github.com/imcuttle/remark-heading-id)
β custom heading id support `{#custom-id}`
* π’ [`remark-heading-gap`](https://github.com/remarkjs/remark-heading-gap)
β serialize w/ more blank lines between headings
* π’ [`@vcarl/remark-headings`](https://github.com/vcarl/remark-headings)
β extract a list of headings as data
* π’ [`remark-hexo`](https://github.com/bennycode/remark-hexo)
β renders [Hexo tags](https://hexo.io/docs/tag-plugins)
* π’ [`remark-highlight.js`](https://github.com/remarkjs/remark-highlight.js)
β highlight code blocks w/
[`highlight.js`](https://github.com/isagalaev/highlight.js)
(rehype compatible)
* π’ [`remark-hint`](https://github.com/sergioramos/remark-hint)
β add hints/tips/warnings to markdown
* π’ [`remark-html`](https://github.com/remarkjs/remark-html)
β serialize markdown as HTML
* β οΈ [`remark-iframes`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-iframes#readme)
β new syntax to create iframes (new node type, rehype compatible)
* π’ [`remark-ignore`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-ignore)
β use comments to exclude nodes from transformation
* π’ [`remark-images`](https://github.com/remarkjs/remark-images)
β add an improved image syntax
* π’ [`remark-img-links`](https://github.com/Pondorasti/remark-img-links)
β prefix relative image paths with an absolute URL
* π’ [`@it-service-npm/remark-include`](https://github.com/IT-Service-NPM/remark-include)
β add `::include{file=path.md}` statements to compose markdown files together
* π’ [`remark-inline-links`](https://github.com/remarkjs/remark-inline-links)
β change references and definitions to links and images
* π’ [`remark-ins`](https://github.com/ipikuka/remark-ins)
β add ins element for inserted texts opposite to deleted texts
* π’ [`remark-join-cjk-lines`](https://github.com/purefun/remark-join-cjk-lines)
β remove extra space between CJK Characters.
* β οΈ [`remark-kbd`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-kbd#readme)
β new syntax for keyboard keys (new node type, rehype compatible)
* β οΈ [`remark-kbd-plus`](https://github.com/twardoch/remark-kbd-plus)
β new syntax for keyboard keys w/ plusses (new node type, rehype
compatible)
* π’ [`remark-license`](https://github.com/remarkjs/remark-license)
β add a license section
* π’ [`remark-link-rewrite`](https://github.com/rjanjic/remark-link-rewrite)
β customize link URLs dynamically
* π’ [`remark-linkify-regex`](https://gitlab.com/staltz/remark-linkify-regex)
β change text matching a regex to links
* π’ [`remark-lint`](https://github.com/remarkjs/remark-lint)
β check markdown code style
* π’ [`remark-man`](https://github.com/remarkjs/remark-man)
β serialize markdown as man pages (roff)
* π’ [`remark-math`](https://github.com/remarkjs/remark-math)
β new syntax for math (new node types, rehype compatible)
* π’ [`remark-mdx`](https://github.com/mdx-js/mdx/tree/main/packages/remark-mdx)
β support MDX (JSX, expressions, ESM)
* π’ [`remark-mentions`](https://github.com/FinnRG/remark-mentions)
β replace @ mentions with links
* π’ [`remark-merge-data`](https://github.com/s-h-a-d-o-w/remark-merge-data)
β merge globally defined data with data declared across code blocks
* π’ [`remark-mermaidjs`](https://github.com/remcohaszing/remark-mermaidjs)
β transform mermaid code blocks into inline SVGs
* π’ [`remark-message-control`](https://github.com/remarkjs/remark-message-control)
β turn some or all messages on or off
* π’ [`remark-normalize-headings`](https://github.com/remarkjs/remark-normalize-headings)
β make sure at most one top-level heading exists
* π’ [`remark-numbered-footnote-labels`](https://github.com/jackfletch/remark-numbered-footnote-labels)
β label footnotes w/ numbers
* π’ [`@agentofuser/remark-oembed`](https://github.com/agentofuser/remark-oembed)
β transform URLs for youtube, twitter, etc. embeds
* π’ [`remark-oembed`](https://github.com/sergioramos/remark-oembed)
β transform URLs surrounded by newlines into *asynchronously* loading
embeds
* π’ [`remark-package-dependencies`](https://github.com/unlight/remark-package-dependencies)
β inject your dependencies
* β οΈ [`remark-parse-yaml`](https://github.com/landakram/remark-parse-yaml)
β parse YAML nodes and expose their value as `parsedValue`
* π’ [`remark-pdf`](https://github.com/inokawa/remark-pdf)
β compile markdown to pdf
* β οΈ [`remark-ping`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-ping#readme)
β new syntax for mentions w/ configurable existence check (new node
type, rehype compatible)
* π’ [`remark-plugin-autonbsp`](https://github.com/denisinvader/remark-plugin-autonbsp)
β replace whitespace with non-breaking spaces
to avoid hanging articles, prepositions and digits
* π’ [`remark-prepend-url`](https://github.com/alxjpzmn/remark-prepend-url)
β prepend an absolute url to relative links
* π’ [`remark-prettier`](https://github.com/remcohaszing/remark-prettier)
β check and format markdown using Prettier
* π’ [`remark-prism`](https://github.com/sergioramos/remark-prism)
β highlight code blocks w/ [Prism](https://prismjs.com/) (supporting most
Prism plugins)
* π’ [`@handlewithcare/remark-prosemirror`](https://github.com/handlewithcarecollective/remark-prosemirror)
β compile markdown to [ProseMirror](https://prosemirror.net/) documents
* β οΈ [`remark-redact`](https://github.com/seafoam6/remark-redact)
β new syntax to conceal text matching a regex
* π’ [`remark-redactable`](https://github.com/code-dot-org/remark-redactable)
β write plugins to redact content from a markdown document,
then restore it later
* π’ [`remark-refer-plantuml`](https://github.com/PrinOrange/remark-refer-plantuml)
β automatically transform PlantUML code into referenced embeddable image URLs
* π’ [`remark-reference-links`](https://github.com/remarkjs/remark-reference-links)
β transform links and images into references and definitions
* π’ [`remark-rehype`](https://github.com/remarkjs/remark-rehype)
β transform to [rehype](https://github.com/rehypejs/rehype)
* π’ [`remark-relative-links`](https://github.com/zslabs/remark-relative-links)
β change absolute URLs to relative ones
* π’ [`remark-remove-comments`](https://github.com/alvinometric/remark-remove-comments)
β remove HTML comments from the processed output
* π’ [`remark-remove-unused-definitions`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-remove-unused-definitions)
β remove unused reference-style link definitions
* π’ [`remark-remove-url-trailing-slash`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-remove-url-trailing-slash)
β remove trailing slashes from the ends of all URL paths
* π’ [`remark-renumber-references`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-renumber-references)
β renumber numeric reference-style link ids contiguously starting from 1
* π’ [`remark-retext`](https://github.com/remarkjs/remark-retext)
β transform to [retext](https://github.com/retextjs/retext)
* π’ [`remark-ruby`](https://github.com/laysent/remark-ruby)
β new syntax for ruby (furigana)
* π’ [`remark-sectionize`](https://github.com/jake-low/remark-sectionize)
β wrap headings and subsequent content in section tags (new node type,
rehype compatible)
* β οΈ [`remark-shortcodes`](https://github.com/djm/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`](https://github.com/akebifiky/remark-simple-plantuml)
β turn PlantUML code blocks to images
* π’ [`remark-slate`](https://github.com/hanford/remark-slate)
β compile markdown to [Slate nodes](https://docs.slatejs.org/concepts/02-nodes)
* π’ [`remark-slate-transformer`](https://github.com/inokawa/remark-slate-transformer)
β compile markdown to
[Slate nodes](https://docs.slatejs.org/concepts/02-nodes)
and Slate nodes to markdown
* π’ [`remark-smartypants`](https://github.com/silvenon/remark-smartypants)
β SmartyPants
* π’ [`remark-smcat`](https://github.com/shedali/remark-smcat)
β state machine cat
* π’ [`remark-sort-definitions`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-sort-definitions)
β reorder reference-style link definitions
* π’ [`remark-sources`](https://github.com/unlight/remark-sources)
β insert source code
* π’ [`remark-strip-badges`](https://github.com/remarkjs/remark-strip-badges)
β remove badges (such as `shields.io`)
* π’ [`remark-strip-html`](https://github.com/craftzdog/remark-strip-html)
β remove HTML
* π’ [`remark-squeeze-paragraphs`](https://github.com/remarkjs/remark-squeeze-paragraphs)
β remove empty paragraphs
* β οΈ [`remark-sub-super`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-sub-super)
β new syntax for super- and subscript (new node types, rehype
compatible)
* β οΈ [`remark-terms`](https://github.com/Nevenall/remark-terms)
β new customizable syntax for special terms and phrases
* π’ [`remark-textr`](https://github.com/remarkjs/remark-textr)
β transform text w/ [`Textr`](https://github.com/shuvalov-anton/textr)
* π’ [`remark-tight-comments`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-tight-comments)
β selectively remove newlines around comments
* π’ [`remark-title`](https://github.com/RichardLitt/remark-title)
β check and add the document title
* π’ [`remark-toc`](https://github.com/remarkjs/remark-toc)
β add a table of contents
* π’ [`remark-torchlight`](https://github.com/torchlight-api/remark-torchlight)
β syntax highlighting powered by [torchlight.dev](https://torchlight.dev)
* π’ [`remark-tree-sitter`](https://github.com/samlanning/remark-tree-sitter)
β highlight code blocks in markdown files using
[Tree-sitter](https://tree-sitter.github.io/tree-sitter/)
(rehype compatible)
* π’ [`remark-truncate-links`](https://github.com/GaiAma/Coding4GaiAma/tree/HEAD/packages/remark-truncate-links)
β truncate/shorten urls not manually named
* π’ [`remark-twemoji`](https://github.com/madiodio/remark-twemoji)
β turn emoji into [Twemoji](https://github.com/twitter/twemoji)
* π’ [`remark-typedoc-symbol-links`](https://github.com/kamranayub/remark-typedoc-symbol-links)
β turn Typedoc symbol link expressions into markdown links
* π’ [`remark-typescript`](https://github.com/trevorblades/remark-typescript)
β turn TypeScript code to JavaScript
* π’ [`remark-typograf`](https://github.com/mavrin/remark-typograf)
β transform text w/ [Typograf](https://github.com/typograf)
* π’ [`remark-unlink`](https://github.com/remarkjs/remark-unlink)
β remove all links, references, and definitions
* π’ [`remark-usage`](https://github.com/remarkjs/remark-usage)
β add a usage example
* π’ [`remark-utf8`](https://github.com/Swizec/remark-utf8)
β turn bolds, italics, and code into UTF 8 special characters
* π’ [`remark-validate-links`](https://github.com/remarkjs/remark-validate-links)
β check links to headings and files
* β οΈ [`remark-variables`](https://github.com/mrzmmr/remark-variables)
β new syntax for variables
* π’ [`remark-vdom`](https://github.com/remarkjs/remark-vdom)
β compile markdown to [VDOM](https://github.com/Matt-Esch/virtual-dom/)
* π’ [`remark-wiki-link`](https://github.com/landakram/remark-wiki-link)
β new syntax for wiki links (rehype compatible)
* π’ [`remark-yaml-config`](https://github.com/remarkjs/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
# 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
## Contents
* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Plugins](#plugins)
* [Examples](#examples)
* [Example: turning markdown into HTML](#example-turning-markdown-into-html)
* [Example: support for GFM and frontmatter](#example-support-for-gfm-and-frontmatter)
* [Example: checking markdown](#example-checking-markdown)
* [Example: checking and formatting markdown on the CLI](#example-checking-and-formatting-markdown-on-the-cli)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [Sponsor](#sponsor)
* [License](#license)
## What is this?
With this project and a plugin,
you can turn this markdown:
```markdown
# Hello, *Mercury*!
```
β¦into the following HTML:
```html
Hello, Mercury!
```
Show example code
```js
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)) // => 'Hello, Mercury!
'
```
Show example code
```js
/**
* @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++
}
})
}
}
```
Hello, Neptune!
```
### 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):
```js
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
Hi MarsVenus!
```
### Example: checking markdown
The following example checks that markdown code style is consistent and follows
recommended best practices:
```js
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:
```sh
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`:
```js
/* β¦ */
"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:
```js
/* β¦ */
"remarkConfig": {
"settings": {
"bullet": "*", // Use `*` for list item bullets (default)
// See 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:
```sh
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):
```js
{
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:
```js
/**
* @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.
## Sponsor
Support this effort and give back by sponsoring on [OpenCollective][]!
## License
[MIT](license) Β© [Titus Wormer](https://wooorm.com)
[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
---
