docs: product-based sidebar sections, and go full width (alternative to #161) - #164
Open
anthonyd-bruno wants to merge 6 commits into
Open
docs: product-based sidebar sections, and go full width (alternative to #161)#164anthonyd-bruno wants to merge 6 commits into
anthonyd-bruno wants to merge 6 commits into
Conversation
The v4 sidebar was six generic buckets (Getting Started, Core Features, API Tools, Developer Tools, License Management, Advanced Guides) that mix products together: the CLI, the VS Code extension, and API documentation all lived under "Developer Tools" next to Bru Lang and the converters, so the sidebar gave no indication of what the separate parts of Bruno are. Replace those buckets with one top-level sidebar section per product, plus sections for the pages that do not belong to a single product: Get Started | API Client | CLI | API Docs | VS Code Extension | Reference | Licensing Notable moves: - CLI is promoted from a subgroup of "Developer Tools" to a top-level section, split into Overview / Install & Quick Start / Run Collections / Configuration / CI/CD. - API Docs and the VS Code extension become top-level sections. API Docs keeps its OpenAPI subgroup and gains a "Write Documentation" subgroup. - Bru Lang, OpenCollection YAML and Converters move to "Reference" — shared formats and tooling rather than one product's features. - "Git Providers" folds into "Git & Collaboration" under API Client. - advanced-guides/visualize moves under Response Data & Cookies, which is what it documents, retiring the one-page "Advanced Guides" bucket. - 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. Mintlify renders these top-level groups as sidebar section headers with their icons, so all seven products stay visible while their subgroups collapse. The API Client icon is "window-maximize", not Lucide's "app-window", which 403s on Mintlify's Font Awesome icon CDN. 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 62 broken links in 38 files as main — none new. v2 and v3 navigation are untouched legacy snapshots; the diff is confined to the v4 block. 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) box with mx-auto, so past that width the box stops growing and the rest of the viewport becomes equal dead margins. docs.json has no content-width option, and the native escape hatches are per-page frontmatter (`mode: "wide"` drops the TOC, `mode: "custom"` drops the sidebar and the TOC) that would have to be pasted into every .mdx. So release the cap in CSS instead. Mintlify auto-injects a root style.css as an inline, unlayered <style>, which is enough to win over the compiled utilities. Two divs carry the cap and both are released, or the navbar would sit on a different grid than the body: the navbar rail (plain `max-w-8xl`) and the wrapper around #sidebar / #content-area / the TOC (the same cap written through Mintlify's `mode` peer variants). `[class*="max-w-8xl"]` matches both without depending on where either sits in the tree. #content-area is the only flex-grow child of the second carrier, so it absorbs the freed width; the sidebar's and TOC's own widths are untouched. Below the width where the cap binds the rule changes nothing, so no media query is needed. The tradeoffs — longer line length, inflating card grids, trailing gutters next to images and narrow tables — are documented inline with the dial to reach for if long measure becomes the complaint. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The Getting Started page opened with two starter-guide cards and a grab bag of task links, but never said what the parts of Bruno are — the same gap the product-shaped sidebar restructure addresses. Lead the page with a "Core products" card grid instead: API Client, CLI, API Docs, and VS Code Extension, each with a one-line description and a link to its section's overview page, using the same icons as their sidebar sections. Supporting cleanup so the page reads as one coherent flow: - Move the intro paragraph into `description` frontmatter so it renders as a subtitle under the page title (a convention the bru-cli pages already use). - Group the existing starter-guide and migration cards under a "Quick starts" heading, since cards no longer sit directly under the intro. - In "Start with a task", replace the "Bruno CLI" card — now redundant with the CLI product card and the CLI Starter Guide card — with an "Authentication" card, keeping Scripting and Variables. - "Explore Public Collections" and "Why Bruno?" are unchanged; prettier reflowed the footnote markup without changing its rendering. The heading is "Core products" rather than "Bruno's core products" because MDX smart-quotes the apostrophe into the anchor slug (#bruno's-core-products with a curly quote); verified the rendered anchor is #core-products. All card links target pages already in the v4 nav. `mint validate` passes, prettier passes, and `mint broken-links` reports the identical 62 pre-existing broken links as main — none new. The v3 copy of this page is a legacy snapshot and stays untouched. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Four regroupings, all inside the v4 sidebar sections introduced by the product restructure. The theme is depth: the section header already spends one level, so umbrella groups and single-page accordions were pushing real content three and four expandable levels down. - Split "Send Requests" into two siblings: "Send Requests" (protocols and history) and "Responses & Cookies" (response data, cookies, response examples, visualize). Response handling was never really "sending requests", and every response page gets one level shallower. - Replace the "Tests & Scripts" umbrella with sibling groups "Testing" (introduction, assertions, Automate Tests) and "Scripting" (the script pages with their Request/Response subgroups). The umbrella added a level without adding meaning — script pages sat four levels deep (API Client > Tests & Scripts > Scripts > Request > page). The "Automate Tests" pages move from the umbrella into "Testing". The api-client/overview card is retitled "Testing & Scripting" to match the new group names. - Unify the Git provider pages. gitlab, bitbucket, and azure-devops sat loose in "Git & Collaboration" while github hid inside a "Git Providers" subgroup — the same kind of content at two different levels. All five (with the providers overview) now live in one "Providers" subgroup, and embed-bruno-collection moves to the end of the group. - Remove two thin accordions. Licensing's "End Users" group held exactly one page (activate-license), which is now a loose page under the section. The CLI's two-page "Install & Quick Start" group hid the entry path behind a click; overview, quick-start, and installation now sit loose above the CLI's topic groups. No files were moved and no page paths changed. All 196 nav pages remain, each exactly once. `mint validate` passes and `mint broken-links` is byte-identical to the main baseline (62 pre-existing broken links in 38 files, none new). v2 and v3 navigation untouched. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The cookies page is request-side content: it opens with "add, send, view, and delete request cookies" and the body is about configuring cookies that go out with requests (plus CLI cookie forwarding between requests in collection runs). Inspecting response cookies is one sentence. So it sits under "Send Requests" now, as a loose page after the protocol groups and before History. The remaining group is renamed "Responses & Cookies" -> "Response Data" (overview, response data, response examples, visualize), and its overview page is retitled from "Response Data and Cookies" to "Response Data" to match, with its Cookies section now linking to the cookies page's new home. Page paths are unchanged (the res-data-cookies directory name is a filesystem detail, not a nav constraint), so no redirects are needed. All 196 nav pages remain, each exactly once. `mint validate` and prettier pass; `mint broken-links` is byte-identical to the main baseline (62 pre-existing, none new). v3's copy of these pages is a legacy snapshot and stays untouched. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…uct-sidebar The SSE page slots into the v4 REST group after body-data, matching its upstream placement. Nav inventory is now 197 pages: upstream's 196 plus api-client/overview. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
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.
Why
Same feedback as #161: the docs are hard to navigate — it isn't easy to find what you need from the sidebar, and it isn't easy to tell what the different parts of Bruno actually 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 the products together.
This PR is the sidebar alternative to #161. Same product taxonomy, different presentation: instead of Mintlify header tabs, the products are top-level sidebar sections, so every product stays visible in one scrollable sidebar and nothing hides behind a tab switch. It also goes further than #161 on the second level, flattening the groups inside each section (details below). Review both and keep one. (#160 is a third, independent exploration of the same feedback.)
What changed
1. Sidebar restructured around Bruno's products (
docs.json)The six buckets are replaced with one top-level sidebar section per product, plus three sections for content that doesn't belong to a single product:
Get Started|API Client|CLI|API Docs|VS Code Extension|Reference|LicensingThe four product sections are the spine. Get Started is the cross-product onboarding path, Reference holds the genuinely shared material (Bru Lang, OpenCollection YAML, converters), and Licensing is orthogonal to all four. Mintlify renders each top-level group as a section header with its icon, with the groups inside it collapsing.
Moves shared with #161:
advanced-guides/visualizemoves under response data, retiring the one-page "Advanced Guides" group.get-started/configure/*becomes "Settings" under API Client.Re-cuts specific to this PR — the section header already spends one sidebar level, so umbrella groups and single-page accordions were pushing real content three and four expandable levels down:
gitlab,bitbucket, andazure-devopssat loose whilegithubhid inside a "Git Providers" subgroup — the same kind of content at two different levels. All five now live in one "Providers" subgroup under "Git & Collaboration".activate-licenseis a loose page), and the CLI's entry path (overview,quick-start,installation) sits loose above its topic groups instead of behind a two-page "Install & Quick Start" accordion.2. New landing pages (
api-client/overview.mdx,introduction/getting-started.mdx)api-client/overview.mdx(new) gives the API Client section a landing page and cross-links the other three products.descriptionfrontmatter (renders as the page subtitle), and the duplicate "Bruno CLI" task card was replaced with "Authentication".3. The docs shell is full width (
style.css, new file)Mintlify centres the whole shell inside a
max-w-8xl(92rem / 1472px) box, leaving the rest of a wide viewport as dead margins. Two elements carry that cap — the navbar rail and the wrapper around the sidebar/content/TOC — and both are released; releasing only one would put the navbar on a different grid from the body.docs.jsonhas no content-width option, and the native escape hatches (per-page frontmattermode: "wide"/"custom") drop chrome we want to keep. Mintlify auto-injects a rootstyle.css, the same mechanism that already loadsreo.jsandwebinar-card.js. Unlike #161, no tab-row CSS is needed — there is no tab row.No files were moved and no page paths changed, so every existing URL still resolves and no redirects are needed. (
send-requests/res-data-cookies/is a filesystem detail, not a nav constraint.)Verification
mainv4 nav are present, each exactly once, plus the newapi-client/overview(197 total). Checked mechanically by a generator script that diffs the nav inventory againstmainand refuses to write on any mismatch.mint validatepasses;mint broken-linksoutput is byte-identical tomain(the same 62 pre-existing broken links in 38 files — none new, measured on a clean worktree ofmainwith the same mint version).mint dev: all seven sections appear as sidebar headers with their icons, the new group labels render, the old ones appear only in the untouched v3 legacy nav, and bothmax-w-8xlcarriers match the CSS.app-windowis a Lucide name and 403s on that CDN — this PR useswindow-maximizefor the API Client icon.v2andv3navigation are byte-identical tomain— legacy version snapshots, deliberately untouched.main(the SSE docs, Server Side Events #156) is merged in, with the SSE page slotted into the REST group at its upstream position.🤖 Generated with Claude Code