From b5f9fd2ec936d434cd2d22a24dab36ab54704414 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Wed, 24 Jun 2026 16:22:02 +0000
Subject: [PATCH] feat(docs): switch mobile-toc default from opt-in to opt-out

Change the default value of mobileToc from false to true so the mobile
table of contents is enabled for all documentation sites by default.
Users can still disable it by setting mobile-toc: false in docs.yml.

Also updates the docs.yml API definition description to reflect the
new opt-out behavior.

Co-Authored-By: mathieu <mathieu@buildwithfern.com>
---
 docs-yml.schema.json                                          | 2 +-
 fern/apis/docs-yml/definition/docs.yml                        | 2 +-
 .../cli/cli/changes/unreleased/mobile-toc-default-true.yml    | 4 ++++
 .../src/docs-yml/parseDocsConfiguration.ts                    | 2 +-
 .../schemas/sdk/api/resources/docs/types/LayoutConfig.ts      | 2 +-
 packages/cli/workspace/loader/src/docs-yml.schema.json        | 2 +-
 6 files changed, 9 insertions(+), 5 deletions(-)
 create mode 100644 packages/cli/cli/changes/unreleased/mobile-toc-default-true.yml

diff --git a/docs-yml.schema.json b/docs-yml.schema.json
index 541bb9df61f9..e28ec64145be 100644
--- a/docs-yml.schema.json
+++ b/docs-yml.schema.json
@@ -6053,7 +6053,7 @@
               "type": "null"
             }
           ],
-          "description": "If `mobile-toc` is set to true, a sticky collapsible table of contents bar will be shown on mobile viewports for guide and overview layout pages."
+          "description": "A sticky collapsible table of contents bar is shown on mobile viewports for guide and overview layout pages by default. Set `mobile-toc` to false to disable it."
         }
       },
       "additionalProperties": false
diff --git a/fern/apis/docs-yml/definition/docs.yml b/fern/apis/docs-yml/definition/docs.yml
index d53750d868b1..79179270d847 100644
--- a/fern/apis/docs-yml/definition/docs.yml
+++ b/fern/apis/docs-yml/definition/docs.yml
@@ -969,7 +969,7 @@ types:
         type: optional<boolean>
         availability: in-development
         docs: |
-          If `mobile-toc` is set to true, a sticky collapsible table of contents bar will be shown on mobile viewports for guide and overview layout pages.
+          A sticky collapsible table of contents bar is shown on mobile viewports for guide and overview layout pages by default. Set `mobile-toc` to false to disable it.
 
   DocsSettingsConfig:
     properties:
diff --git a/packages/cli/cli/changes/unreleased/mobile-toc-default-true.yml b/packages/cli/cli/changes/unreleased/mobile-toc-default-true.yml
new file mode 100644
index 000000000000..d36747a7d727
--- /dev/null
+++ b/packages/cli/cli/changes/unreleased/mobile-toc-default-true.yml
@@ -0,0 +1,4 @@
+- summary: |
+    Switch mobile-toc default from opt-in (false) to opt-out (true) so the
+    mobile table of contents is enabled for all documentation sites by default.
+  type: feat
diff --git a/packages/cli/configuration-loader/src/docs-yml/parseDocsConfiguration.ts b/packages/cli/configuration-loader/src/docs-yml/parseDocsConfiguration.ts
index a5312aff4124..94f11c866c33 100644
--- a/packages/cli/configuration-loader/src/docs-yml/parseDocsConfiguration.ts
+++ b/packages/cli/configuration-loader/src/docs-yml/parseDocsConfiguration.ts
@@ -657,7 +657,7 @@ function convertLayoutConfig(
         disableHeader: layout.disableHeader ?? false,
         hideNavLinks: layout.hideNavLinks ?? false,
         hideFeedback: layout.hideFeedback ?? false,
-        mobileToc: layout.mobileToc ?? false,
+        mobileToc: layout.mobileToc ?? true,
         tabsAlignment: resolvedTabsAlignment
     } as unknown as docsYml.ParsedDocsConfiguration["layout"];
 }
diff --git a/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/LayoutConfig.ts b/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/LayoutConfig.ts
index 704fc6c69881..0aa1b9a92aeb 100644
--- a/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/LayoutConfig.ts
+++ b/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/LayoutConfig.ts
@@ -94,6 +94,6 @@ export interface LayoutConfig {
     hideNavLinks?: boolean;
     /** If `hide-feedback` is set to true, the feedback button will not be rendered. This can be overridden for a specific page using the frontmatter. */
     hideFeedback?: boolean;
-    /** If `mobile-toc` is set to true, a sticky collapsible table of contents bar will be shown on mobile viewports for guide and overview layout pages. */
+    /** A sticky collapsible table of contents bar is shown on mobile viewports for guide and overview layout pages by default. Set `mobile-toc` to false to disable it. */
     mobileToc?: boolean;
 }
diff --git a/packages/cli/workspace/loader/src/docs-yml.schema.json b/packages/cli/workspace/loader/src/docs-yml.schema.json
index 541bb9df61f9..e28ec64145be 100644
--- a/packages/cli/workspace/loader/src/docs-yml.schema.json
+++ b/packages/cli/workspace/loader/src/docs-yml.schema.json
@@ -6053,7 +6053,7 @@
               "type": "null"
             }
           ],
-          "description": "If `mobile-toc` is set to true, a sticky collapsible table of contents bar will be shown on mobile viewports for guide and overview layout pages."
+          "description": "A sticky collapsible table of contents bar is shown on mobile viewports for guide and overview layout pages by default. Set `mobile-toc` to false to disable it."
         }
       },
       "additionalProperties": false