diff --git a/cspell.json b/cspell.json
index 62598f846..4475099a8 100644
--- a/cspell.json
+++ b/cspell.json
@@ -163,6 +163,7 @@
         "Joar",
         "josephfrazier",
         "jscodefmt",
+        "jscodeshift",
         "jsesc",
         "jsfmt",
         "jsonata",
diff --git a/docs/api.md b/docs/api.md
index 6d17c6946..1fd27c64a 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -132,18 +132,19 @@ The support information looks like this:
 }
 ```
 
-## Custom Parser API
+<a name="custom-parser-api"></a>
 
-If you need to make modifications to the AST (such as codemods), or you want to provide an alternate parser, you can do so by setting the `parser` option to a function. The function signature of the parser function is:
+## Custom Parser API (deprecated)
+
+_Will be removed in v3.0.0 (superseded by the Plugin API)_
+
+Before [plugins](plugins.md) were a thing, Prettier had a similar but more limited feature called custom parsers. It will be removed in v3.0.0 as its functionality is a subset of what the Plugin API does. If you used it, please check the example below on how to migrate.
+
+❌ Custom parser API (deprecated):
 
 ```js
-(text: string, parsers: object, options: object) => AST;
-```
-
-Prettier’s built-in parsers are exposed as properties on the `parsers` argument.
-
-```js
-prettier.format("lodash ( )", {
+import { format } from "prettier";
+format("lodash ( )", {
   parser(text, { babel }) {
     const ast = babel(text);
     ast.program.body[0].expression.callee.name = "_";
@@ -153,4 +154,30 @@ prettier.format("lodash ( )", {
 // -> "_();\n"
 ```
 
-The `--parser` CLI option may be a path to a node.js module exporting a parse function.
+✔️ Plugin API:
+
+```js
+import { format } from "prettier";
+import parserBabel from "prettier/parser-babel.js";
+const myCustomPlugin = {
+  parsers: {
+    "my-custom-parser": {
+      parse(text) {
+        const ast = parserBabel.parsers.babel.parse(text);
+        ast.program.body[0].expression.callee.name = "_";
+        return ast;
+      },
+      astFormat: "estree",
+    },
+  },
+};
+format("lodash ( )", {
+  parser: "my-custom-parser",
+  plugins: [myCustomPlugin],
+});
+// -> "_();\n"
+```
+
+> Note: Overall, doing codemods this way isn’t recommended. Prettier uses the location data of AST nodes for many things like preserving blank lines and attaching comments. When the AST is modified after the parsing, the location data often gets out of sync, which may lead to unpredictable results. Consider using [jscodeshift](https://github.com/facebook/jscodeshift) if you need codemods.
+
+As part of the deprecated Custom parser API, it is possible to pass a path to a module exporting a `parse` function via the `--parser` option. Use the `--plugin` CLI option or the `plugins` API option instead to [load plugins](plugins.md#using-plugins).
diff --git a/docs/options.md b/docs/options.md
index 38cadabd3..60ce3d3ac 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -281,7 +281,7 @@ Valid options:
 - `"lwc"` (same parser as `"html"`, but also formats LWC-specific syntax for unquoted template attributes) _First available in 1.17.0_
 - `"yaml"` (via [yaml](https://github.com/eemeli/yaml) and [yaml-unist-parser](https://github.com/ikatyang/yaml-unist-parser)) _First available in 1.14.0_
 
-[Custom parsers](api.md#custom-parser-api) are also supported. _First available in v1.5.0_
+[Custom parsers](api.md#custom-parser-api) are also supported. _First available in v1.5.0. Deprecated. Will be removed in v3.0.0 (superseded by the Plugin API)_
 
 | Default | CLI Override                                    | API Override                                               |
 | ------- | ----------------------------------------------- | ---------------------------------------------------------- |
diff --git a/website/versioned_docs/version-stable/api.md b/website/versioned_docs/version-stable/api.md
index 958d0bae2..a8288f272 100644
--- a/website/versioned_docs/version-stable/api.md
+++ b/website/versioned_docs/version-stable/api.md
@@ -133,18 +133,19 @@ The support information looks like this:
 }
 ```
 
-## Custom Parser API
+<a name="custom-parser-api"></a>
 
-If you need to make modifications to the AST (such as codemods), or you want to provide an alternate parser, you can do so by setting the `parser` option to a function. The function signature of the parser function is:
+## Custom Parser API (deprecated)
+
+_Will be removed in v3.0.0 (superseded by the Plugin API)_
+
+Before [plugins](plugins.md) were a thing, Prettier had a similar but more limited feature called custom parsers. It will be removed in v3.0.0 as its functionality is a subset of what the Plugin API does. If you used it, please check the example below on how to migrate.
+
+❌ Custom parser API (deprecated):
 
 ```js
-(text: string, parsers: object, options: object) => AST;
-```
-
-Prettier’s built-in parsers are exposed as properties on the `parsers` argument.
-
-```js
-prettier.format("lodash ( )", {
+import { format } from "prettier";
+format("lodash ( )", {
   parser(text, { babel }) {
     const ast = babel(text);
     ast.program.body[0].expression.callee.name = "_";
@@ -154,4 +155,30 @@ prettier.format("lodash ( )", {
 // -> "_();\n"
 ```
 
-The `--parser` CLI option may be a path to a node.js module exporting a parse function.
+✔️ Plugin API:
+
+```js
+import { format } from "prettier";
+import parserBabel from "prettier/parser-babel.js";
+const myCustomPlugin = {
+  parsers: {
+    "my-custom-parser": {
+      parse(text) {
+        const ast = parserBabel.parsers.babel.parse(text);
+        ast.program.body[0].expression.callee.name = "_";
+        return ast;
+      },
+      astFormat: "estree",
+    },
+  },
+};
+format("lodash ( )", {
+  parser: "my-custom-parser",
+  plugins: [myCustomPlugin],
+});
+// -> "_();\n"
+```
+
+> Note: Overall, doing codemods this way isn’t recommended. Prettier uses the location data of AST nodes for many things like preserving blank lines and attaching comments. When the AST is modified after the parsing, the location data often gets out of sync, which may lead to unpredictable results. Consider using [jscodeshift](https://github.com/facebook/jscodeshift) if you need codemods.
+
+As part of the deprecated Custom parser API, it is possible to pass a path to a module exporting a `parse` function via the `--parser` option. Use the `--plugin` CLI option or the `plugins` API option instead to [load plugins](plugins.md#using-plugins).
diff --git a/website/versioned_docs/version-stable/options.md b/website/versioned_docs/version-stable/options.md
index 2b8a012ba..a1c39b50d 100644
--- a/website/versioned_docs/version-stable/options.md
+++ b/website/versioned_docs/version-stable/options.md
@@ -282,7 +282,7 @@ Valid options:
 - `"lwc"` (same parser as `"html"`, but also formats LWC-specific syntax for unquoted template attributes) _First available in 1.17.0_
 - `"yaml"` (via [yaml](https://github.com/eemeli/yaml) and [yaml-unist-parser](https://github.com/ikatyang/yaml-unist-parser)) _First available in 1.14.0_
 
-[Custom parsers](api.md#custom-parser-api) are also supported. _First available in v1.5.0_
+[Custom parsers](api.md#custom-parser-api) are also supported. _First available in v1.5.0. Deprecated. Will be removed in v3.0.0 (superseded by the Plugin API)_
 
 | Default | CLI Override                                    | API Override                                               |
 | ------- | ----------------------------------------------- | ---------------------------------------------------------- |