diff --git a/packages/mdx/lib/core.js b/packages/mdx/lib/core.js
index eaec0dec1..c7adc329f 100644
--- a/packages/mdx/lib/core.js
+++ b/packages/mdx/lib/core.js
@@ -52,6 +52,9 @@
  *   the automatic runtime compiles to `import _jsx from
  *   '$importSource/jsx-runtime'\n_jsx('p')`;
  *   the classic runtime compiles to calls such as `h('p')`.
+ *
+ *   > 👉 **Note**: support for the classic runtime is deprecated and will
+ *   > likely be removed in the next major version.
  * @property {ReadonlyArray<string> | null | undefined} [mdExtensions]
  *   List of markdown extensions, with dot (default: `['.md', '.markdown', …]`);
  *   affects integrations.
@@ -71,12 +74,18 @@
  *   `'React.createElement'`);
  *   when changing this, you should also define `pragmaFrag` and
  *   `pragmaImportSource` too.
+ *
+ *   > 👉 **Note**: support for the classic runtime is deprecated and will
+ *   > likely be removed in the next major version.
  * @property {string | null | undefined} [pragmaFrag='React.Fragment']
  *   Pragma for fragment symbol, used in the classic runtime as an identifier
  *   for unnamed calls: `<>` to `React.createElement(React.Fragment)` (default:
  *   `'React.Fragment'`);
  *   when changing this, you should also define `pragma` and
  *   `pragmaImportSource` too.
+ *
+ *   > 👉 **Note**: support for the classic runtime is deprecated and will
+ *   > likely be removed in the next major version.
  * @property {string | null | undefined} [pragmaImportSource='react']
  *   Where to import the identifier of `pragma` from, used in the classic
  *   runtime (default: `'react'`);
@@ -84,6 +93,9 @@
  *   the following will be generated: `import a from 'c'` and things such as
  *   `a.b('h1', {})`.
  *   when changing this, you should also define `pragma` and `pragmaFrag` too.
+ *
+ *   > 👉 **Note**: support for the classic runtime is deprecated and will
+ *   > likely be removed in the next major version.
  * @property {string | null | undefined} [providerImportSource]
  *   Place to import a provider from (optional, example: `'@mdx-js/react'`);
  *   normally it’s used for runtimes that support context (React, Preact), but
@@ -148,6 +160,8 @@ const removedOptions = [
   'wrapExport'
 ]
 
+let warned = false
+
 /**
  * Create a processor to compile markdown or MDX to JavaScript.
  *
@@ -181,6 +195,19 @@ export function createProcessor(options) {
     )
   }
 
+  if (
+    !warned &&
+    (settings.jsxRuntime === 'classic' ||
+      settings.pragma ||
+      settings.pragmaFrag ||
+      settings.pragmaImportSource)
+  ) {
+    warned = true
+    console.warn(
+      "Unexpected deprecated option `jsxRuntime: 'classic'`, `pragma`, `pragmaFrag`, or `pragmaImportSource`; see <https://mdxjs.com/migrating/v3/> on how to migrate"
+    )
+  }
+
   const pipeline = unified().use(remarkParse)
 
   if (settings.format !== 'md') {
diff --git a/packages/mdx/readme.md b/packages/mdx/readme.md
index 503a9fc40..7064e0160 100644
--- a/packages/mdx/readme.md
+++ b/packages/mdx/readme.md
@@ -691,6 +691,9 @@ Configuration for `createProcessor` (TypeScript type).
     '$importSource/jsx-runtime'\n_jsx('p')`;
     the classic runtime compiles to calls such as `h('p')`
 
+    > 👉 **Note**: support for the classic runtime is deprecated and will
+    > likely be removed in the next major version.
+
     <details><summary>Expand example</summary>
 
     If `file` is the contents of `example.mdx` from [§ Use][use], then:
@@ -778,6 +781,9 @@ Configuration for `createProcessor` (TypeScript type).
     when changing this, you should also define `pragmaFrag` and
     `pragmaImportSource` too
 
+    > 👉 **Note**: support for the classic runtime is deprecated and will
+    > likely be removed in the next major version.
+
     <details><summary>Expand example</summary>
 
     If `file` is the contents of `example.mdx` from [§ Use][use], then:
@@ -812,13 +818,19 @@ Configuration for `createProcessor` (TypeScript type).
     for unnamed calls: `<>` to `React.createElement(React.Fragment)`;
     when changing this, you should also define `pragma` and `pragmaImportSource`
     too
-*    `pragmaImportSource` (`string`, default: `'react'`)
+
+    > 👉 **Note**: support for the classic runtime is deprecated and will
+    > likely be removed in the next major version.
+*   `pragmaImportSource` (`string`, default: `'react'`)
     — where to import the identifier of `pragma` from, used in the classic
     runtime;
     to illustrate, when `pragma` is `'a.b'` and `pragmaImportSource` is `'c'`
     the following will be generated: `import a from 'c'` and things such as
     `a.b('h1', {})`;
     when changing this, you should also define `pragma` and `pragmaFrag` too
+
+    > 👉 **Note**: support for the classic runtime is deprecated and will
+    > likely be removed in the next major version.
 *   `providerImportSource` (`string`, optional, example: `'@mdx-js/react'`)
     — place to import a provider from;
     normally it’s used for runtimes that support context (React, Preact), but
diff --git a/packages/mdx/test/compile.js b/packages/mdx/test/compile.js
index 6ecd8ef1e..01c96bd64 100644
--- a/packages/mdx/test/compile.js
+++ b/packages/mdx/test/compile.js
@@ -28,6 +28,39 @@ test('@mdx-js/mdx: compile', async function (t) {
     }, /Unexpected removed option `filepath`/)
   })
 
+  await t.test(
+    'should warn about the deprecated classic runtime',
+    async function () {
+      const warn = console.warn
+      /** @type {Array<unknown> | undefined} */
+      let messages
+
+      console.warn = capture
+
+      assert.equal(
+        renderToStaticMarkup(
+          React.createElement(
+            await run(await compile('# hi!', {jsxRuntime: 'classic'}))
+          )
+        ),
+        '<h1>hi!</h1>'
+      )
+
+      assert.deepEqual(messages, [
+        "Unexpected deprecated option `jsxRuntime: 'classic'`, `pragma`, `pragmaFrag`, or `pragmaImportSource`; see <https://mdxjs.com/migrating/v3/> on how to migrate"
+      ])
+
+      console.warn = warn
+
+      /**
+       * @param  {...unknown} args
+       */
+      function capture(...args) {
+        messages = args
+      }
+    }
+  )
+
   await t.test('should compile', async function () {
     assert.equal(
       renderToStaticMarkup(