From 4aec93401c8d9a80b03a021e00cfa2e120ac5ff6 Mon Sep 17 00:00:00 2001 From: ukimsanov Date: Tue, 28 Jul 2026 19:32:48 -0700 Subject: [PATCH] docs: simplify navigation hierarchy --- docs/custom.css | 60 +++++++++++++++++++ docs/docs.json | 52 ++++------------ research/docs-refactor/NOTES.md | 8 +++ research/docs-refactor/rebuild-navigation.mjs | 51 ++++------------ 4 files changed, 92 insertions(+), 79 deletions(-) diff --git a/docs/custom.css b/docs/custom.css index b4cb460fa4..cbec7d0535 100644 --- a/docs/custom.css +++ b/docs/custom.css @@ -148,6 +148,66 @@ a:not([class]):hover { opacity: 0.85; } +/* ── On-page navigation ── */ + +#table-of-contents-content { + position: relative; + margin-left: 4px; +} + +#table-of-contents-content::before { + position: absolute; + top: 8px; + bottom: 8px; + left: 0; + width: 1px; + background: var(--hf-border-color-light); + content: ''; +} + +#table-of-contents-content .toc-item { + border-left: 0 !important; +} + +#table-of-contents-content .toc-item > a { + position: relative; + border-left-color: transparent !important; +} + +#table-of-contents-content .toc-item[data-depth='0'] > a::before { + position: absolute; + top: 50%; + left: -4px; + width: 7px; + height: 7px; + border: 2px solid var(--hf-background); + border-radius: 999px; + background: var(--hf-border-color-light); + content: ''; + transform: translateY(-50%); +} + +#table-of-contents-content .toc-item[data-depth='0'] > a[class*='border-primary']::before { + background: var(--hf-accent-green); +} + +#table-of-contents-content .toc-item[data-depth='1'] { + margin-left: 1px; + padding-left: 18px; +} + +#table-of-contents-content .toc-item[data-depth='1']::before { + position: absolute; + top: 0; + left: -1px; + width: 14px; + height: 50%; + border-bottom: 1px solid var(--hf-border-color-light); + border-left: 1px solid var(--hf-border-color-light); + border-bottom-left-radius: 8px; + content: ''; +} + /* Catalog texture examples */ .hf-texture-preview-panel { diff --git a/docs/docs.json b/docs/docs.json index a9a5af5ef8..792b56ea15 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -50,12 +50,8 @@ { "tab": "Guides", "icon": "book-open", - "groups": [ - { - "group": "Guides", - "root": "guides/index", - "directory": "card", - "pages": [ + "pages": [ + "guides/index", { "group": "Start here", "root": "introduction", @@ -99,7 +95,7 @@ ] }, { - "group": "Learn", + "group": "Concepts", "root": "concepts/index", "expanded": false, "pages": [ @@ -139,13 +135,7 @@ "guides/performance" ] }, - { - "group": "Examples", - "expanded": false, - "pages": [ - "examples" - ] - }, + "examples", { "group": "Help", "root": "guides/help", @@ -158,26 +148,20 @@ }, { "group": "What's new", + "root": "product-updates", "expanded": false, "pages": [ - "product-updates", "weekly-updates", "changelog" ] } - ] - } ] }, { "tab": "Studio", "icon": "palette", - "groups": [ - { - "group": "Studio", - "root": "studio/index", - "directory": "card", - "pages": [ + "pages": [ + "studio/index", "studio/tour", { "group": "Review", @@ -218,19 +202,13 @@ "studio/troubleshooting" ] } - ] - } ] }, { "tab": "Catalog", "icon": "grid-2", - "groups": [ - { - "group": "Catalog", - "root": "catalog/index", - "directory": "card", - "pages": [ + "pages": [ + "catalog/index", { "group": "Code Animations", "pages": [ @@ -431,19 +409,13 @@ ], "expanded": false } - ] - } ] }, { "tab": "Developers", "icon": "code", - "groups": [ - { - "group": "Developers", - "root": "developers/index", - "directory": "card", - "pages": [ + "pages": [ + "developers/index", { "group": "Command line", "expanded": true, @@ -524,8 +496,6 @@ "community/adopters" ] } - ] - } ] } ] diff --git a/research/docs-refactor/NOTES.md b/research/docs-refactor/NOTES.md index 73e590b7d4..4d19f1fe0f 100644 --- a/research/docs-refactor/NOTES.md +++ b/research/docs-refactor/NOTES.md @@ -190,6 +190,14 @@ New navigation should be task-shaped: - `oxlint` passed for changed scripts; - `git diff --check` passed. +### 2026-07-28 — navigation polish after preview review + +- Removed the redundant Guides, Studio, Catalog, and Developers parent groups beneath tabs with the same names. +- Kept each tab overview as a normal first page and placed collapsible sections directly below it. +- Restored the clearer **Concepts** label and made all multi-page sections collapsible. +- Added a lightweight visual rail, active marker, and nested branch to Mintlify's generated **On this page** navigation. +- Confirmed the result in a local Mintlify preview; validation and broken-link checks still pass. + ## Maintenance issue - The repo instructions refer to `.agents/skills/hyperframes/SKILL.md`, but that repo-local path is absent in this checkout. The installed current router at `/Users/ularkimsanov/.agents/skills/hyperframes/SKILL.md` was used as the workflow source of truth for this pass. diff --git a/research/docs-refactor/rebuild-navigation.mjs b/research/docs-refactor/rebuild-navigation.mjs index 280481ebf4..5516f6a37a 100644 --- a/research/docs-refactor/rebuild-navigation.mjs +++ b/research/docs-refactor/rebuild-navigation.mjs @@ -61,12 +61,8 @@ config.navigation = { { tab: "Guides", icon: "book-open", - groups: [ - { - group: "Guides", - root: "guides/index", - directory: "card", - pages: [ + pages: [ + "guides/index", { group: "Start here", root: "introduction", @@ -110,7 +106,7 @@ config.navigation = { ], }, { - group: "Learn", + group: "Concepts", root: "concepts/index", expanded: false, pages: [ @@ -150,11 +146,7 @@ config.navigation = { "guides/performance", ], }, - { - group: "Examples", - expanded: false, - pages: ["examples"], - }, + "examples", { group: "Help", root: "guides/help", @@ -163,22 +155,17 @@ config.navigation = { }, { group: "What's new", + root: "product-updates", expanded: false, - pages: ["product-updates", "weekly-updates", "changelog"], + pages: ["weekly-updates", "changelog"], }, - ], - }, ], }, { tab: "Studio", icon: "palette", - groups: [ - { - group: "Studio", - root: "studio/index", - directory: "card", - pages: [ + pages: [ + "studio/index", "studio/tour", { group: "Review", @@ -217,31 +204,21 @@ config.navigation = { "studio/troubleshooting", ], }, - ], - }, ], }, { tab: "Catalog", icon: "grid-2", - groups: [ - { - group: "Catalog", - root: "catalog/index", - directory: "card", - pages: collapsedCatalogGroups, - }, + pages: [ + "catalog/index", + ...collapsedCatalogGroups, ], }, { tab: "Developers", icon: "code", - groups: [ - { - group: "Developers", - root: "developers/index", - directory: "card", - pages: [ + pages: [ + "developers/index", { group: "Command line", expanded: true, @@ -314,8 +291,6 @@ config.navigation = { "community/adopters", ], }, - ], - }, ], }, ],