diff --git a/.changeset/shaggy-keys-turn.md b/.changeset/shaggy-keys-turn.md
index 07cc06c95dc0..999557344150 100644
--- a/.changeset/shaggy-keys-turn.md
+++ b/.changeset/shaggy-keys-turn.md
@@ -16,3 +16,48 @@ Refine Markdown and MDX configuration options for ease-of-use.
 
 - Support _all_ Markdown configuration options (except `drafts`) from your MDX integration config. This includes `syntaxHighlighting` and `shikiConfig` options to further customize the MDX renderer.
 - Simplify `extendDefaults` to an `extendMarkdownConfig` option. MDX options will default to their equivalent in your Markdown config. By setting `extendMarkdownConfig` to false, you can "eject" to set your own syntax highlighting, plugins, and more.
+
+## Migration
+
+To preserve your existing Markdown and MDX setup, you may need some configuration changes:
+
+### Smartypants manual installation
+
+[Smartypants](https://github.com/silvenon/remark-smartypants) has been removed from Astro's default setup. If you rely on this plugin, [install `remark-smartypants`](https://github.com/silvenon/remark-smartypants#installing) and apply to your `astro.config.*`:
+
+```diff
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
++ import smartypants from 'remark-smartypants';
+
+export default defineConfig({
+  markdown: {
++   remarkPlugins: [smartypants],
+  }
+});
+```
+
+### Migrate `extendDefaultPlugins` to `githubFlavoredMarkdown`
+
+You may have disabled Astro's built-in plugins (GitHub-Flavored Markdown and Smartypants) with the `extendDefaultPlugins` option. Since Smartypants has been removed, this has been renamed to `githubFlavoredMarkdown`.
+
+```diff
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  markdown: {
+-   extendDefaultPlugins: false,
++   githubFlavoredMarkdown: false,
+  }
+});
+```
+
+
+Additionally, applying remark and rehype plugins **no longer disables** `githubFlavoredMarkdown`. You will need to opt-out manually by setting `githubFlavoredMarkdown` to `false`.
+
+### Migrate MDX's `extendPlugins` to `extendMarkdownConfig`
+
+You may have used the `extendPlugins` option to manage plugin defaults in MDX. This has been replaced by 2 flags:
+- `extendMarkdownConfig` (`true` by default) to toggle Markdown config inheritance. This replaces the `extendPlugins: 'markdown'` option.
+- `githubFlavoredMarkdown` (`true` by default) to toggle GitHub-Flavored Markdown in MDX. This replaces the `extendPlugins: 'defaults'` option.