diff --git a/src/content/docs/en/guides/markdown-content.mdx b/src/content/docs/en/guides/markdown-content.mdx
index 051adc85e8bc8..ff60658d03219 100644
--- a/src/content/docs/en/guides/markdown-content.mdx
+++ b/src/content/docs/en/guides/markdown-content.mdx
@@ -598,8 +598,8 @@ export default defineConfig({
       // https://shiki.style/themes
       theme: 'dracula',
       // Alternatively, provide multiple themes
-      // https://shiki.style/guide/dual-themes
-      themes: {
+      // See note below for using dual light/dark themes
+      experimentalThemes: {
         light: 'github-light',
         dark: 'github-dark',
       },
@@ -617,6 +617,10 @@ export default defineConfig({
 });
 ```
 
+:::note[Customizing Shiki themes]
+Astro code blocks are styled using the `.astro-code` class. When following Shiki's documentation (e.g. to [customize light/dark dual or multiple themes](https://shiki.style/guide/dual-themes#query-based-dark-mode)), be sure to replace the `.shiki` class in the examples with `.astro-code`
+:::
+
 #### Adding your own theme
 
 Instead of using one of Shiki’s predefined themes, you can import a custom theme from a local file.