diff --git a/code.mdx b/code.mdx
index f0854a5aa..023352229 100644
--- a/code.mdx
+++ b/code.mdx
@@ -63,6 +63,8 @@ Enable syntax highlighting by specifying the programming language after the open
 
 We use [Shiki](https://shiki.style/) for syntax highlighting and support all available languages. See the full list of [languages](https://shiki.style/languages) in Shiki's documentation.
 
+Customize code block themes globally using `styling.codeblocks` in your `docs.json` file. Set simple themes like `system` or `dark`, or configure custom [Shiki themes](https://shiki.style/themes) for light and dark modes. See [Settings](/settings#styling) for configuration options.
+
 <CodeGroup>
 
 ```java Syntax highlighting example
diff --git a/components/code-groups.mdx b/components/code-groups.mdx
index a4694711e..f8574ecbc 100644
--- a/components/code-groups.mdx
+++ b/components/code-groups.mdx
@@ -26,6 +26,8 @@ class HelloWorld {
 
 </CodeGroup>
 
+Code groups inherit global styling from your `docs.json` file. Customize your theme using `styling.codeblocks`. See [Settings](/settings#styling) for configuration options.
+
 ## Creating code groups
 
 To create a code group, wrap multiple code blocks with `<CodeGroup>` tags. Each code block must include a title, which becomes the tab label.
diff --git a/settings.mdx b/settings.mdx
index 770ed07cf..4f01d6307 100644
--- a/settings.mdx
+++ b/settings.mdx
@@ -127,8 +127,51 @@ See [Themes](themes) for more information.
     <ResponseField name="eyebrows" type="&quot;section&quot; | &quot;breadcrumbs&quot;">
       The style of the page eyebrow. Choose `section` to show the section name or `breadcrumbs` to show the full navigation path. Defaults to `section`.
     </ResponseField>
-    <ResponseField name="codeblocks" type="&quot;system&quot; | &quot;dark&quot;">
-      The theme of the code blocks. Choose `system` to match the site theme or `dark` for always dark code blocks. Defaults to `system`.
+    <ResponseField name="codeblocks" type="&quot;system&quot; | &quot;dark&quot; | string | object">
+      Code block theme configuration. Defaults to `"system"`.
+
+      **Simple configuration:**
+      - `"system"`: Match current site mode (light or dark)
+      - `"dark"`: Always use dark mode
+
+      **Custom theme configuration:**
+      - Use a string to specify a single [Shiki theme](https://shiki.style/themes) for all code blocks
+      - Use an object to specify separate [Shiki themes](https://shiki.style/themes) for light and dark modes
+      
+      <ResponseField name="theme" type="string">
+        A single Shiki theme name to use for both light and dark modes.
+
+        ```json
+        "styling": {
+          "codeblocks": {
+            "theme": "dracula"
+          }
+        }
+        ```
+      </ResponseField>
+
+      <ResponseField name="theme" type="object">
+        Separate themes for light and dark modes.
+
+        <Expandable title="theme">
+        <ResponseField name="light" type="string" required>
+          A Shiki theme name for light mode.
+        </ResponseField>
+        <ResponseField name="dark" type="string" required>
+          A Shiki theme name for dark mode.
+        </ResponseField>
+        ```json
+        "styling": {
+          "codeblocks": {
+            "theme": {
+              "light": "github-light",
+              "dark": "github-dark"
+            }
+          }
+        }
+        ```
+        </Expandable>
+       </ResponseField>
     </ResponseField>
   </Expandable>
 </ResponseField>