docs: split API Docs features, More menu, Mock Servers placeholder - #170
Open
anthonyd-bruno wants to merge 7 commits into
Open
docs: split API Docs features, More menu, Mock Servers placeholder#170anthonyd-bruno wants to merge 7 commits into
anthonyd-bruno wants to merge 7 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>
anthonyd-bruno
changed the base branch from
docs/restructure-by-product
to
main
August 11, 2026 17:05
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
…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>
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
1 participant
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.
Note
Stacked on #163: this branch builds on
docs/restructure-by-product, and the first commits in the diff are #163's. It targetsmain(rather than the base branch) because Mintlify only builds preview deployments for PRs againstmain. Review only the last commit here; merge #163 first and this diff collapses to just the new work.What this does
1. Separates writing docs from generated HTML docs (API Docs tab)
Feedback was that the in-app markdown docs and the auto-generated HTML docs read as one confusing feature. The tab now has two clearly-named groups:
html-docs/section split fromapi-docs/auto-generate-docsat its existing headings: Overview, Generate Docs, Environments, Search, Interactive Playground, Deploy & ShareThe tab overview is rewritten as a two-feature router (card comparison + how the features connect).
/api-docs/auto-generate-docsgets a permanent redirect to/html-docs/overview, which also covers the absolute link from the v3 overview.2. Collapses Reference + Licensing into a "More" navbar menu
Clicking More opens a dropdown with the two sections (with descriptions) plus a curated list of popular pages: JavaScript API Reference, Postman Migration, Environment Variables, OAuth 2.0. Popular links use single-page
pagesentries — the schema'sitem+hrefvariant is broken in the renderer (drops the href, lands on the default page).3. Adds a Mock Servers tab as a structural placeholder
One coming-soon overview page under
mock-servers/, slotted between API Docs and VS Code Extension. Note: this is publicly visible once deployed — hold this if the release shouldn't be signaled yet (or we can addnoindex).4. Fixes silently-blank icons
Mintlify resolves icon names against Font Awesome, not Lucide, and
mint validatedoesn't catch invalid names — they just render as empty space. Fixedbraces→brackets-curly,arrow-right-left→right-left,layers→layer-group, and the API Client tab'sapp-window→browser(blank since #163).Verification
mint validatepasses;mint broken-linksreports the same pre-existing set as the base branch, none newhtml-docs/*(redirected from the old page)🤖 Generated with Claude Code