style: clustered single-bar nav, root home page, content sync + link audit - #182
Open
anthonyd-bruno wants to merge 17 commits into
Open
style: clustered single-bar nav, root home page, content sync + link audit#182anthonyd-bruno wants to merge 17 commits into
anthonyd-bruno wants to merge 17 commits into
Conversation
Feedback was that the sidebar made it hard to find things and hard to tell what the different parts of Bruno are. The v4 sidebar was a single flat list of six generic buckets (Getting Started, Core Features, API Tools, Developer Tools, License Management, Advanced Guides) that mixed products together — the CLI, VS Code extension, and API documentation all lived under "Developer Tools" alongside Bru Lang and converters. Replace those buckets with Mintlify tabs, one per product: Get Started | API Client | CLI | API Docs | VS Code Extension | Reference | Licensing Notable moves: - Bruno CLI is promoted from a subgroup to its own tab, split into Overview / Run Collections / Configuration / CI/CD. - API Docs and the VS Code extension become top-level tabs. - "Git Providers" folds into "Git & Collaboration". - advanced-guides/visualize moves under Response Data & Cookies, which is what it documents, retiring the one-page "Advanced Guides" group. - get-started/configure/* becomes "Settings" under API Client. Add api-client/overview.mdx as the API Client landing page; it also cross-links the other three products so each part of Bruno is discoverable from the others. No files were moved and no page paths changed, so every existing URL still resolves and no redirects are needed. All 195 previously navigable pages remain in the nav, each exactly once. `mint validate` passes and `mint broken-links` reports the same 99 pre-existing broken links as main — none new. v2 and v3 navigation are left untouched as legacy snapshots. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The tab row is a shrink-to-fit flex container, so the seven product tabs bunched against the left gutter — at a 1440px viewport .nav-tabs measured 796px inside 1344px of available space, leaving ~548px of dead air on the right. Let .nav-tabs grow to fill its px-12 rail and hand the free space to justify-content: space-between. Tabs keep their intrinsic widths, so the leftover width is divided equally between the six gaps. Measured (light + dark, /introduction/getting-started, /bru-cli/overview and /license-overview, via puppeteer against the dev server): width gaps (each) bar span 1024 45.93px 48 -> 976 flush both edges 1280 88.59px 48 -> 1232 flush both edges 1440 115.26px 48 -> 1392 flush both edges 1920 120.59px 272 -> 1648 flush both edges 2560 120.59px 592 -> 1968 flush both edges Gap spread is exactly 0.00px at every width — all six gaps identical. The first tab stays flush with the logo gutter and the last tab lands on the header controls' alignment line. The navbar's existing max-w-8xl ancestor caps the row at 1376px, so gaps self-limit at ~121px on ultrawide rather than growing without bound. Deliberately minimal — two declarations, nothing applied to .nav-tabs-item: - The underline indicator needs no CSS. Anchors keep their intrinsic width, so each indicator still spans its own tab box; measured identical to baseline (100.16px Get Started, 46.01px CLI, 88.32px Licensing) in both themes. - The rule is a no-op once free space runs out, so today's shrink/wrap fallback is preserved. Verified byte-identical to baseline at 1024px with root font-size 24px (981.4px bar, last tab right edge 1053.4px both with and without the rule). Approaches adding min-width:0, overflow-x:auto, flex:0 0 auto or per-item padding were tested and rejected: each converts that reachable fallback into silently clipped or hidden tabs under browser font scaling. - Scoped to min-width:1024px to match the wrapper's `hidden lg:flex`, so the mobile dropdown is untouched (confirmed hidden at 800px and 1023px). The breakpoint is px on purpose — Tailwind compiles `lg` to px, verified at root font sizes 12/16/20px. Mintlify auto-loads a root style.css, the same mechanism that already loads reo.js and webinar-card.js. `mint validate` passes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Mintlify centres the whole shell — sidebar, article and table of contents — inside a max-w-8xl (92rem = 1472px) box with mx-auto. Past that width the box stops growing and the remainder becomes equal dead margins: 224px per side at 1920px, 544px per side at 2560px, with nothing rendered in them. Two elements carry the cap and both must be released or the navbar ends up on a different grid from the body: the navbar rail (a plain `max-w-8xl` utility) and the wrapper around #sidebar/#content-area/the TOC (the same cap written through Mintlify's per-page `mode` peer variants). A single `[class*="max-w-8xl"]` selector matches both without coupling to either element's position in the tree. docs.json has no content-width option — `styling` accepts only `eyebrows` and `codeblocks` — and the native escape hatches are per-page frontmatter `mode: "custom"` (drops sidebar and TOC) and `mode: "wide"` (drops the TOC), which remove chrome we want and would need pasting into every .mdx. So CSS is the only route. Measured on /send-requests/REST/rest-api: viewport content column sidebar x TOC right edge 1280 528.8px 32 1248 (no-op) 1440 688.8px 32 1408 (no-op) 1472 720.8px 32 1440 (no-op) 1473 721.8px 32 1441 (first change) 1920 1168.8px 32 1888 2560 1808.8px 32 2528 No media query is needed: the rule releases the cap exactly where the cap binds, so it is a measured no-op at every width up to 1472px — most laptops see no change at all. Mobile is untouched (content 460px at 500px viewport, 760px at 800px, both unchanged). No horizontal overflow appears at any width. The rule caps nothing, so every element keeps a single shared right edge. Three capping variants were built and measured and all scored worse: capping the content column strands the TOC across a void of up to 1461px at 3440px, and capping prose alone gives the page two different right margins that read as a misalignment bug. Interaction with the nav-tab rule: the cap used to bound the tab rail at 1376px, so its gaps settled at ~121px. Uncapped they track the viewport — 195px at 1920, 302px at 2560. Gaps remain exactly equal (spread 0.00px at every width) and the rail stays flush with the wordmark and header controls, so it is left unbounded; every way of bounding it reinstates the dead margin this change removes. Known costs on very wide screens, documented in style.css: prose measure grows from 78 characters to 124 at 1920 and 198 at 2560, and Mintlify's card grids top out at 2 columns so cards inflate rather than reflow. Both are dials that can be turned if they become the complaint. `mint validate` passes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Builds on the product-based navigation restructure (#163). - Separate writing docs in the app from the generated-HTML-docs feature, which shared one "Create Documentation" group and read as a single feature. The API Docs tab now has "Write Docs in Bruno" (workspace/collection/folder/request) and "Generate HTML Docs" (new html-docs/ pages split from api-docs/auto-generate-docs at its existing headings: overview, generate, environments, search, playground, deploy). The tab overview is rewritten as a two-feature router page. /api-docs/auto-generate-docs redirects to /html-docs/overview; the four writing pages keep their paths. - Collapse the Reference and Licensing tabs into a "More" tab that opens a navbar menu, and append a curated list of popular pages (JavaScript reference, Postman migration, environment variables, OAuth 2.0). The popular links use single-page `pages` entries because the schema's item+href variant drops the href on click and lands on the site's default page. - Add a Mock Servers tab as a structural placeholder for the upcoming release, with a single coming-soon overview page. - Fix icon names that silently rendered blank: Mintlify resolves icons against Font Awesome, not Lucide, and mint validate does not catch bad names. braces/arrow-right-left/layers become brackets-curly/right-left/layer-group, and the API Client tab's app-window (blank since the restructure) becomes browser. mint validate passes; mint broken-links reports no new breaks. Menu navigation and icon rendering verified in a headless browser. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…images Mintlify's theme defaults are 16px/1.75 body text, 48px above every h2, 32px around every image, full-column screenshots, and 36px sidebar rows. None of that is our content. Override it in style.css (Mintlify loads every .css file in the repo): - Body text 16px -> 14.5px, line-height 1.75 -> 1.55. The prose theme sizes headings and most margins in em, so this compounds across the whole page. (Cursor's docs, the density benchmark, use 14px.) - Heading margins cut (h2 top margin 48px -> ~33px). - Paragraph and list margins reduced, including between list items. - Screenshots capped at min(580px, 100%) with halved vertical margins. - Callouts: 14px text, padding 16/20px -> 10/14px. - Sidebar: 13px text, 36px -> 27px rows. Measured at 1440x900: /html-docs/generate 2511px -> 2136px (-15%), the JavaScript reference 52709px -> 47694px (-9.5%), visible sidebar rows 13 -> 16 / 14 -> 18. The floor on long pages is code blocks (left readable on purpose) and screenshot heights. No horizontal overflow; computed styles verified in a headless browser. Each override is an independent labeled block with plain-number values, so any single choice can be tuned or deleted without the rest. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- New Home tab: "What would you like help with?" hero, search CTA that opens the real search modal, and a 4-across tile grid for every tab - Hover dropdowns on nav tabs listing each tab's sections (nav-dropdowns.js) - Rename Reference tab to Formats (shapes icon); OpenAPI first after Overview, Bru Lang last - Overview pages with tile grids for API Client, CLI, VS Code Extension, Licensing, Git & Collaboration, and Scripts (replaces Getting Started) - Getting Started and API Client overviews at 3 tiles per row; Explore Public Collections converted to a full-width tile - Segmented-control tab styling with responsive compaction, dark-mode search modal fixes, sidebar density tweaks (style.css) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Restyle the nav tabs as a card-index folder stack: equal-width tabs, flat left edge with a rounded right shoulder, each tucked behind the previous one, with the active tab popping forward with a grey fill. Fix the active-tab hook (Mintlify never emits data-active; match its text-shadow utility class instead) and drop the per-tab and Popular dropdown chevrons. Align the shell Cursor-style: sidebar pinned to the viewport's left edge with a subtle panel fill, navbar rail and tab row trimmed to the same 16px so wordmark, tabs and sidebar share one left edge (NB: #navbar is a div, not <header> — tag-prefixed selectors match nothing). Rename the "VS Code Extension" tab to "VS Code" so equal-width tabs fit at laptop widths. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Merge the tab row into the wordmark row (design handoff option 1c, adapted): one header bar with the wordmark, then the tabs as monochrome text pills split into PRODUCTS and MORE groups by hairline dividers and small sans eyebrow labels (hidden below 1250px), search pinned to the bar's right end (field on wide bars, icon + shortcut below 1450px). The five header links (API Reference, Blog, Support, Changelog, Roadmap) are removed from docs.json — a Download button will take that corner. Drop the Home tab: home.mdx becomes index.mdx and serves at the bare domain root (with a /home -> / redirect), so the wordmark is the way home. Restore the mode:center width cap that the full-width shell rule was accidentally releasing on the home page, and reorganize home into Start / Products / More sections of compact horizontal cards with one-line descriptions. Also: suppress the lingering pointer-focus ring on the Popular menu tab, and tighten the wordmark/version/tabs spacing. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…toggle The <1250px compaction tier sat above the base pill rules; every rule in it ties on specificity and a media query adds none, so the later base rules won at every width and the tier never applied (only the label display:none survived). The tab row kept its full ~875px width down to 1024px and ran under the pinned search entry (overlap from ~1197px, 173px deep at 1024px) and the theme toggle (from ~1110px). Moved the tier below the base rules so source order lets it win, with a comment pinning it there. Measured after: compacted row ends at x=842, 44px clear of search at 1024px; >=1250px tiers and the 1450px search breakpoint byte-identical; no horizontal overflow at any width. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The frontmatter title doubles as the hero h1 and the tab/SEO title for the docs root; the old question phrasing read as a support portal and looked odd in browser tabs and search results. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…, rich-text docs Content sync with the published site (40 commits, merge-base Aug 5). Conflict resolutions, all in favor of the newer content: - mock-servers/overview.mdx: took upstream's released Beta docs over our 'coming soon' stub; registered create/run pages in the Mock Servers tab (one group, tagged Beta like upstream's) and gave the tab a dropdown. - api-docs/auto-generate-docs.mdx: stayed deleted (split into html-docs/* on this branch); upstream's one-line edit (search across folders) is ported to html-docs/search.mdx. The existing redirect covers old links. - docs.json: kept our tabbed v4 nav and ported upstream's changes into it: boost:3 on Variables/Scripts/Secret Managers and the CLI tab's groups, Beta tag on Apps, Google Cloud Secret Manager group, bru-lang/yaml-migration, and the PostHog integration key. Also fixed the VS Code tab's dropdown key in nav-dropdowns.js — the map said 'VS Code Extension' but the tab label is 'VS Code', so its dropdown never attached. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Full link audit of the branch (2,179 internal links, all mdx + docs.json + custom JS). Every broken link found is also broken on the published site today — none were introduced by the restructure, whose redirect coverage checked out complete (the only two published URLs gone from this branch both already redirect). Link fixes (36): missing /get-started and /secret-managers path segments, group-index URLs linked without /overview, a self-page link to the never-published /mock-servers/create-and-run, /agents/introduction -> the v4 AI integration guide, and 'Bruno v4 release notes' -> the real usebruno.com/v4-release URL. v2/v3 pages now link in-version (/v2/..., /v3/...) where the target exists. Image fixes (8 paths, 7 files): doubled /images/images/ prefixes and v2-prefixed license screenshots that only exist at the root images/. New redirects (10): the group-index secret-manager URLs, and the wrong paths that published pages have been linking (create-and-run, agents/introduction, import-export/bruno-basics unprefixed paths, oauth2-experimental/request-level-configuration) — these are live 404s likely indexed, so they redirect permanently to the right pages. Verified on mint dev: static audit reports 0 broken links / 0 missing assets; all 10 redirect sources 307 to their destinations; browser click-through passes on home search CTA + cards, tab links, hover dropdowns (incl. the new Mock Servers and fixed VS Code ones), Popular menu, theme menu, version switcher (v3 navigates), sidebar links, and the search modal (result list needs the hosted index, unavailable to local dev — UI verified). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
Mintlify's hosted renderer emits different markup than the local CLI, which broke two class-coupled hooks on the deployed preview only: - Popular's star icon ships as size-4 (dev: h-4) and its menu caret as viewBox="0 0 18 18" (dev: "0 -9 3 24"), so the enumerated icon-hide rule missed both and the tab grew ~47px. The rule is now a blanket hide of every svg inside a tab (sparing our injected dropdown panels) so renderer drift can't reintroduce icons. - Production adds an "Ask Assistant" button (#assistant-entry) beside search in the pinned corner wrapper — absent from dev builds — adding ~150px. The corner now compacts in tiers sized against the measured tab-row widths (~1059px labelled / ~842px compacted): <1520px the assistant drops to its icon, <1450px the search field drops to icon + ⌘K (existing), <1250px the ⌘K hint goes too. Verified locally (no regression: row clears the corner at every width >=1024, wider margins below 1250) — production verification on the rebuilt preview. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ng tabs The <1250px compaction tier (smaller font, tighter padding, no group labels) is gone by request: tabs now render at full size or not at all. Since the full labelled row measures ~1059px and cannot share 1024-1249px with the wordmark and corner controls, the shell keeps Mintlify's mobile mode through that range instead of flipping to desktop at lg (1024px): - The two desktop-nav blocks (sidebar shell, single-bar clustered nav) are rescoped from min-width:1024px to 1250px. - A new forced-mobile block for 1024-1249.98px re-flips the lg: variants (every mobile element is in the DOM at desktop widths, hidden purely by CSS): hides the tab row, desktop search corner, and #sidebar; re-shows the mobile icon cluster, the drawer trigger bar, and the drawer's portal overlay (which is lg-gated outside #navbar and needs its own rule); drops the content area's sidebar gutter. - The <1250px ⌘K tier is deleted (moot: nothing below 1250 is desktop). Hooks verified identical in both renderers (hosted and local CLI). Verified locally at 900/1024/1100/1249/1250/1300/1449/1920: mobile through 1249 (drawer opens with version/tab pickers and nav, mobile search icon opens the modal), desktop from 1250, no horizontal overflow, <1024 byte-identical to stock. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The hosted renderer rasterizes the labelled tab row ~16px wider than dev (~1075px vs ~1059px), leaving 1px of air at exactly 1250px and 6px at 1520px on the preview. Hide the search ⌘K hint below 1280px and keep the assistant label off until 1536px, buying ~29px and ~22px at those edges. Comment now records both renderers' row widths and sizes tiers against the hosted one. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Supersedes #172 — same branch content, freshly synced with
mainand carrying the follow-up fixes below.Single-bar clustered nav (from the "option 1c" design handoff, adapted): the tab row merges into the wordmark row — one header bar containing the logo/version, then the tabs as quiet monochrome text pills, grouped by hairline dividers with small eyebrow labels (PRODUCTS, MORE). The active tab is a soft grey pill. Group labels hide below 1250px (dividers stay); tab icons are gone per the spec. Hover section-dropdowns list each tab's sections.
Search is pinned to the bar's right end — a real field on wide screens, icon + ⌘K below 1450px. The five header links (API Reference, Blog, Support, Changelog, Roadmap) are removed from docs.json; that corner is reserved for a Download button (follow-up).
Home at the root: the Home tab is gone — the wordmark links home.
home.mdxis renamedindex.mdxso it serves at the bare domain (docs.usebruno.com/), with a permanent/home → /redirect for existing links. Headline: "Bruno Documentation" (doubles as the tab/SEO title for the docs root).Home page: reorganized into Start / Products / More sections mirroring the nav groups, with compact horizontal cards (icon + title + one-line description). Also fixes a real bug: the full-width shell rule was accidentally releasing the home page's
mode: centerwidth cap, stretching its content across the full viewport.Narrow-desktop overlap fix: the <1250px compaction tier sat above the base pill rules in style.css and lost every cascade tie, so it never applied — below ~1200px the full-width tab row ran under the pinned search field and theme toggle. The tier now sits below the base rules (source order is what lets it win; a comment pins it there). Measured clear at every width ≥1024px.
Synced with
main(40 commits, merge-base Aug 5): mock servers (released Beta docs replace the earlier "coming soon" stub — the tab lists all three pages, Beta-tagged, with a hover dropdown), Google Cloud Secret Manager, Bru→YAML migration, rich-text docs revamp, PostHog key, search boosts. The docs.json conflict was resolved by porting main's changes into the tabbed nav. Also fixed the VS Code tab's dropdown key in nav-dropdowns.js (said "VS Code Extension", never matched the renamed tab).Link audit (2,179 internal links across mdx, docs.json, custom JS): fixed 36 broken links and 8 broken image paths — every one is also broken on the published site today; none came from this restructure, whose redirect coverage checked out complete. Added 10 permanent redirects for wrong paths that published pages have been linking (likely indexed):
/mock-servers/create-and-run,/agents/introduction, the secret-manager group-index URLs, un-prefixed/import-export-data/...&/bruno-basics/..., andoauth2-experimental/request-level-configuration.Verification
On
mint dev: static audit reports 0 broken links / 0 missing assets; all redirect sources 307 to their destinations; browser click-through passes on home search CTA + cards, tab links, hover dropdowns, Popular menu, theme menu, version switcher, and sidebar links. Search results need the hosted index (unavailable to local dev) — please try one search on this preview.Review notes
#navbar,#search-bar-entry,.nav-tabs-item,data-component-part). Failure direction is stock styling; re-check after Mintlify bumps./api-clientand/referenceroute prefixes — reordering tabs or moving those first pages in docs.json requires updating the hooks in style.css (documented inline).🤖 Generated with Claude Code