From e1d78382cc379513fbd57f39b5d5d135c3d71642 Mon Sep 17 00:00:00 2001
From: TomShawn <41534398+TomShawn@users.noreply.github.com>
Date: Tue, 4 Aug 2026 13:46:56 +0800
Subject: [PATCH] Docs: refine docs layout to widen content area

On a 16" screen the article column rendered at only ~760px because the
docs pages inherited the 1200px `--global-main-width` shared with the
marketing pages, leaving wide empty gutters on both sides while the
sidebar, TOC and article fought over what was left.

Docs pages now use the full viewport, capped at 1920px so lines stay
readable on ultra-wide screens. The TOC moves from a percentage-based
col--3 to a fixed 288px column, so every remaining pixel goes to the
article instead of inflating the TOC on large screens. The article
column grows to fill whatever is left.

This also aligns two stale breakpoints (1440px) in the DocItem and
DocRoot layouts with the 1280px breakpoint design-style.scss already
uses to hide the TOC. Between 1280px and 1440px the TOC was rendered
next to an article still claiming 100% width, which squeezed the TOC
down to ~185px.

Measured article width at 1728px viewport: 760px -> 921px.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 src/css/custom.scss                           |  9 ++++++++
 src/theme/DocItem/Layout/index.tsx            |  6 ++++-
 src/theme/DocItem/Layout/styles.module.css    | 22 +++++++++++++++----
 .../DocRoot/Layout/Main/styles.module.css     |  2 +-
 src/theme/DocRoot/Layout/styles.module.scss   |  5 +----
 5 files changed, 34 insertions(+), 10 deletions(-)

diff --git a/src/css/custom.scss b/src/css/custom.scss
index f1319ac2b8a..67d9f85c34e 100644
--- a/src/css/custom.scss
+++ b/src/css/custom.scss
@@ -88,6 +88,7 @@
   --normal-box-radius: 10px;
   --doc-sidebar-width: 280px;
   --docs-nav-margin: 60px;
+  --doc-toc-width: 288px;
 
   /* === Docusaurus / Infima overrides ========================== */
   --ifm-color-primary: var(--brand-orange-deep);
@@ -185,6 +186,14 @@
     --global-main-width: 100%;
   }
 }
+
+/* Docs pages need far more room than the marketing pages: the layout has to
+   fit the left sidebar, the TOC and the article itself. Let them use the whole
+   viewport (capped so lines stay readable on ultra-wide screens) instead of
+   the 1200px shared with the rest of the site. */
+html.docs-wrapper {
+  --global-main-width: min(100%, 1920px);
+}
 @media screen and (max-width: 1024px) {
   :root {
     --mobile-padding-width: 24px;
diff --git a/src/theme/DocItem/Layout/index.tsx b/src/theme/DocItem/Layout/index.tsx
index 0d40e192f1a..b9f95aef417 100644
--- a/src/theme/DocItem/Layout/index.tsx
+++ b/src/theme/DocItem/Layout/index.tsx
@@ -58,7 +58,11 @@ export default function DocItemLayout({ children }: Props): JSX.Element {
           <DocItemPaginator />
         </div>
       </div>
-      {docTOC.desktop && <div className="col col--3">{docTOC.desktop}</div>}
+      {docTOC.desktop && (
+        <div className={clsx('col col--3', styles.docTocCol)}>
+          {docTOC.desktop}
+        </div>
+      )}
     </div>
   );
 }
diff --git a/src/theme/DocItem/Layout/styles.module.css b/src/theme/DocItem/Layout/styles.module.css
index 25efe7621c2..35940c2b7e2 100644
--- a/src/theme/DocItem/Layout/styles.module.css
+++ b/src/theme/DocItem/Layout/styles.module.css
@@ -3,13 +3,27 @@
   margin-top: 0;
 }
 
-@media (min-width: 1024px) {
+/* 1280px is where design-style.scss stops hiding the TOC column, so the two
+   have to agree. When they disagreed (1280 vs 1440), everything between those
+   two widths rendered the TOC alongside an article still claiming 100%, which
+   squeezed the TOC down to ~185px. */
+@media (min-width: 1280px) {
+  /* The TOC only needs a fixed column; every remaining pixel goes to the
+     article instead of being locked up in a percentage-based col--3. */
   .docItemCol {
-    max-width: 70% !important;
-    margin-right: 40px;
+    flex: 1 1 auto;
+    max-width: calc(100% - var(--doc-toc-width)) !important;
+    margin-right: 0;
+  }
+
+  /* !important: Infima's own .col--3 rule (flex: 0 0 25%) wins otherwise. */
+  .docTocCol {
+    flex: 0 0 var(--doc-toc-width) !important;
+    max-width: var(--doc-toc-width);
   }
 }
-@media screen and (max-width: 1440px) {
+/* Below 1280px the TOC is hidden, so the article spans the full width. */
+@media screen and (max-width: 1280px) {
   .docItemCol {
     max-width: calc(100%) !important;
     margin-right: 0;
diff --git a/src/theme/DocRoot/Layout/Main/styles.module.css b/src/theme/DocRoot/Layout/Main/styles.module.css
index b332be8b6fd..68f03ac76fa 100644
--- a/src/theme/DocRoot/Layout/Main/styles.module.css
+++ b/src/theme/DocRoot/Layout/Main/styles.module.css
@@ -19,7 +19,7 @@
     ) !important;
   }
 }
-@media screen and (max-width: 1440px) {
+@media screen and (max-width: 1280px) {
   .docMainContainer {
     max-width: calc(
       100vw - var(--doc-sidebar-width) - var(--docs-nav-margin) - 140px
diff --git a/src/theme/DocRoot/Layout/styles.module.scss b/src/theme/DocRoot/Layout/styles.module.scss
index 11cc003aa66..4557d599e44 100644
--- a/src/theme/DocRoot/Layout/styles.module.scss
+++ b/src/theme/DocRoot/Layout/styles.module.scss
@@ -12,10 +12,7 @@
 .docsWrapper {
   display: flex;
   flex: 1 0 auto;
-  @media screen and (min-width: 1600px) {
-    width: 1600px !important;
-    max-width: 1600px !important;
-  }
+  width: 100%;
   @media screen and (min-width: 1024px) {
     table {
       th {