From 4cd2136613224fe975fc157d4c742cf4aeb05549 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 29 Sep 2025 13:00:49 -0700
Subject: [PATCH 1/2] add styling.codeblocks docs

---
 code.mdx                   |  2 ++
 components/code-groups.mdx |  2 ++
 settings.mdx               | 47 ++++++++++++++++++++++++++++++++++++--
 3 files changed, 49 insertions(+), 2 deletions(-)

diff --git a/code.mdx b/code.mdx
index c89d9da7c..c01c37c3a 100644
--- a/code.mdx
+++ b/code.mdx
@@ -59,6 +59,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.
+
 ```java
 class HelloWorld {
     public static void main(String[] args) {
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..6c18f3338 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": {
+            "themes": {
+              "light": "github-light",
+              "dark": "github-dark"
+            }
+          }
+        }
+        ```
+        </Expandable>
+       </ResponseField>
     </ResponseField>
   </Expandable>
 </ResponseField>

From dd845056b1cf32a7b33e152dae90c60a4feb2062 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Tue, 30 Sep 2025 11:40:41 -0700
Subject: [PATCH 2/2] reviewer feedback

Co-authored-by: Kathryn Isabelle Lawrence <lawr3ka@gmail.com>
---
 settings.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/settings.mdx b/settings.mdx
index 6c18f3338..4f01d6307 100644
--- a/settings.mdx
+++ b/settings.mdx
@@ -163,7 +163,7 @@ See [Themes](themes) for more information.
         ```json
         "styling": {
           "codeblocks": {
-            "themes": {
+            "theme": {
               "light": "github-light",
               "dark": "github-dark"
             }