prettier-plugin-markdown-replacements weekly downloads statistics

prettier-plugin-markdown-replacements

English | 한국어

A Prettier plugin that applies the text replacements you register to Markdown and MDX documents, and leaves code spans, code blocks and MDX comments exactly as written.

Register the spellings you keep getting wrong, or the notation your project has settled on, and they are corrected every time a document is formatted.

Contents

• Requirements • Installation • Configuration • Rule formats • Why replacements run in the formatter • What is protected • Writing rules that span whitespace • Recipes • Using it with other plugins • Options • Compatibility • Development • License

Requirements

| Item | Version |

| Node.js | 18 or later | | Prettier | 3.5.3 or later |

Installation

Install it as a dev dependency alongside Prettier.

The package is an ES module, so name it in plugins rather than loading it with require(). Prettier 3's plugin loader handles ES modules directly, from any configuration file format.

Configuration

Add the package to plugins and list your rules. The default is empty, so nothing is replaced until you add one.

Before

After

Prose in the body, in headings, in lists and in table cells is corrected, while anything wrapped in code markup keeps its original spelling.

Rule formats

| Format | Example | Behavior |

| Literal | Javascript=>JavaScript | Compared as a plain string and replaced at every occurrence | | Regular expression | /Max ([0-9]+)/g=>Maximum: $1 | Written as /pattern/flags, with capture references such as $1 available |

With the regular expression above, Max 50 becomes Maximum: 50. The g flag is added automatically when omitted, so every occurrence is replaced.

• The separator is the first => in a literal rule, and the => after the flags in a regular expression rule. The replacement itself may contain =>. • Nothing is trimmed, so leading and trailing spaces are part of the rule. • Rules are applied in array order, and the output of one rule is the input of the next. • An entry without a separator or with an empty left side is ignored while the remaining rules still run. • An entry that starts with / but does not read as a regular expression rule, because the pattern is invalid or a flag is unknown, is treated as a literal rule. That keeps a path rewrite such as /docs/guide=>/docs/tutorial working, and it also means a mistyped regular expression matches nothing rather than failing loudly. • The flags are the ones the running JavaScript engine accepts. The v flag needs Node.js 20 or later; on Node.js 18 a rule that uses it is read as a literal rule. • In a JSON configuration file every backslash in the pattern is written twice, because JSON uses the backslash as an escape character itself. The rule //gi=> is stored as "//gi=> ".

Why replacements run in the formatter

Prettier decides how a document is printed and does not change what it says. A replacement changes the content, so putting one in a Prettier plugin is a deliberate choice rather than an oversight, and it is worth saying why.

Formatting is the one step that already runs on every document, in the editor on each save and in CI on each commit. A separate rewriting pass would need its own invocation, its own file discovery and its own ignore rules, and a spelling that slipped past it would sit in the repository until somebody noticed. Registering the rule here means the notation a project has settled on is applied at the moment the document is formatted, so a formatted document is a corrected one.

The rest of this page follows from that choice. A rule sees the whole source at once, which is why one that reaches across a line break rewrites the document's structure, and why the regions that have to survive verbatim are lifted out before any rule runs. When a rule turns out to be broad enough to be destructive, the plugin leaves the document exactly as it was.

What is protected

Replacements run on the document source before it is parsed, and these regions are lifted out first and put back untouched.

| Region | Example |

| Inline code | ` Javascript ` | | Fenced code blocks | and `` | | Indented code blocks | a block indented by four spaces or by a tab | | MDX comments | {/* ... */} |

A string that must survive verbatim, such as a value an API really returns, is protected by wrapping it in code markup.

A fence is recognized at any nesting depth, including inside a list item, whether a blank line precedes it or it sits right under the list marker. An indented code block is recognized at the top level only: inside a list item or a blockquote, four spaces mean ordinary content rather than code, and the plugin tracks no container nesting, so it leaves those alone rather than risk treating list content as code and silently skipping replacements there. Fence the code that is nested in another block. An unclosed fence protects the rest of the document, which is how CommonMark reads it and how Prettier prints it. A fence whose info string names a Markdown language, such as md, is formatted by Prettier as an embedded document through this same parser; the rules stay out of it all the same.

There is one safeguard on top of that. A pattern broad enough to match the internal tokens used to protect those regions would leak a token into the document, so when that happens the document is left exactly as it was. A rule such as /[A-Za-z_]+/g=>X therefore does nothing rather than something destructive.

Writing rules that span whitespace

Replacements see the whole document at once, not one paragraph at a time, and in Markdown a line break carries structure. A pattern that reaches across one is a structural edit, not a spelling fix. Two failures show up quickly.

| Pattern | What it breaks |…

Description from the npm listing.