docs: v1.4.1 overhaul — docs-first homepage, plugins/routing/providers sections, full accuracy pass - #6
Merged
Merged
Conversation
* feat(docs): updated docs
…curacy pass Rebuild ferrolabs-docs around the v1.4.0/v1.4.1 gateway. An audit of all 36 pages against the v1.2.0–v1.4.1 changelog found 1 fresh, 17 stale, 18 wrong; every page was corrected against the ai-gateway source, and the site was restructured into a clean, enterprise documentation experience. Information architecture - Intro is now served at the site root (slug: /); the marketing landing page is removed and /intro/ 301s to /. Docs-style homepage with sidebar. - New per-plugin section /plugins/* (system overview + 6 built-in plugin pages + a Managed-plugins page), replacing the single guides/plugins page. - New per-strategy section /routing/* (overview + all 8 strategies), replacing guides/routing-policies. - New /providers (logo grid + endpoint-support matrix) and /providers/configuration (per-provider env vars), replacing the three guides/providers* pages. - New /guides/dashboard documenting the embedded v1.4.0 dashboard. - guides/admin-auth merged into guides/auth. All moves have server-side 301s in static/_redirects plus client-redirect fallbacks; internal links repointed. Accuracy (grounded in ai-gateway source) - Fixed startup-breaking config examples (budget/cache/logger multi-stage entries now carry identical config), 402 insufficient_quota (was 429), scoped /metrics, SkipProvider (was removed Context.Skip), targets-as-allowlist, retry under every routing mode, FERRO_OLLAMA_MODELS, MASTER_KEY, base-URL-verbatim, per-IP rate limit on by default, real OTel var surface, /livez + /readyz, MCP stdio transport, and more across every rewritten page. - Backfilled the changelog with v1.2.0 → v1.4.1; refreshed the OpenAPI spec (version + new endpoints); FAQ fully rewritten. Design & SEO - Self-hosted Inter + JetBrains Mono variable fonts (retire Roobert); preload + immutable cache headers. - 30 colored provider logos vendored to static/img/providers/. - Single source of product facts (src/data/product.ts) wired into footer/intro; fixes v1.0.0/29-providers/Go 1.24 drift everywhere. - Security headers (HSTS, nosniff, Referrer-Policy, Permissions-Policy), sitemap lastmod + /search exclusion, JSON-LD version bump, robots + llms.txt refresh. - check-doc-accuracy.mjs: drop the now-valid model_prefix ban, add an accuracy-ok escape and this audit's wrong-token denylist. Verified: pnpm typecheck, check:frontmatter, check:docs, and pnpm build all pass.
|
Too many files changed for review (132 files, 100 file limit). Bypass the limit by tagging |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
h1 3rem->2.25rem, h2 2.1rem->1.75rem; nudge h3 1.55rem->1.4rem to keep the hierarchy gap below the smaller h2.
h1 30px, h2 22px, h3 18px (from 36/28/22).
…d heading sizes The page title uses Infima's .markdown h1:first-child (3rem) and section headings use .markdown > h2 (2rem) / > h3 (1.5rem), which override the :root --ifm-hN vars. Re-point those scoped rules with !important so the compact scale wins. Verified in-browser: h1 30px, h2 22px (was 48/34).
Links were all one weight/color, so parents, leaves, and the active page read flat. Now: leaf links in softer slate at a lighter weight; collapsible parents in full ink + 600; the active page in teal + 650 with a tinted pill; clearer hover. Verified in-browser (active 650/teal, parent 600/ink, leaf 450/slate).
…ng, short labels The sidebar was a ~65-row flat list. Now: Routing (8), Plugins (7), SDKs (7), Frameworks (13), Deployment (5), Migrations (3) and Ferro Labs Managed live in collapsed categories whose header links to the section overview; redundant self-labeled rows removed; MCP/Dashboard/strategy/plugin labels shortened to nav-length. Default view is ~38 rows. Pixel pass: nested children drop the per-item icon (parent row carries it), get a smaller size and an indent guide; the link-category caret button is restyled as the rotating chevron instead of being hidden (expandability was invisible); right-hand TOC tightened (0.85rem, muted ink, teal active). Verified in-browser at 1440px on / and /routing/fallback/.
…t group The link run was absolutely page-centered, but the right group (GitHub + theme + search) is ~2x the brand's width, so page-centering left a ~330px hole after the logo and ~90px before GitHub. The run now centers in the free space between its neighbours via symmetric auto margins (container gap cancelled on the brand side). Measured 226px/226px, all three groups on one vertical midline.
…ions, gated - _headers: X-Robots-Tag: noindex on /search/* (robots.txt Disallow blocks crawling but not indexing from external links) - Trim the 10 meta descriptions over 170 chars (homepage, frameworks pages, kubernetes, oss-vs-managed, litellm migration) to ~140-165 - check:frontmatter now enforces description length bounds (50-170) so truncation-length descriptions fail CI instead of drifting back
…le-load, Scalar pinning, schema cleanup From the 6-pass SEO audit of this branch's build (report in workspace docs/audits/docs.ferrolabs.ai-audit/): - 404 page was in sitemap.xml with a self-canonical and no noindex — excluded via sitemap ignorePatterns + X-Robots-Tag noindex in _headers - Added 301s for two previously-live URLs deleted in earlier releases with no redirect: /guides/workspace-sign-in-domains/ -> /guides/auth/, /sdks/overview/ -> /integrations/sdk/openai-compatible/ - Fonts downloaded twice: preload pointed at /fonts/* while webpack rewrote the CSS url() to a hashed /assets/fonts/ copy. @font-face now lives as a raw head <style> so preload and CSS share one URL (~86 KB saved per cold load) - Scalar API-reference script was unpinned jsdelivr "latest" on every page — now vendored (static/js/scalar-api-reference-1.64.0.js), same-origin, version-pinned, immutable-cached. Route-scoping to /api tracked as follow-up - Removed deprecated HowTo schema (fly-io); merged the homepage's duplicate SoftwareApplication into the site-wide entity (license + sameAs folded in); added WebSite SearchAction for the real /search/?q= endpoint - Fixed brand drift "Ferro AI Gateway" -> "Ferro Labs AI Gateway" in 7 files, including 3 meta descriptions AI engines quote Verified in rebuilt output: pinned script src, single font URL, one SoftwareApplication, SearchAction present, HowTo gone, /404/ out of sitemap; typecheck + frontmatter + accuracy checks + full build green.
…M-alternative intent, homepage category keywords - Scalar bundle no longer loads on every page: local plugin fork (src/plugins/scalar-lazy, MIT-derived from @scalar/docusaurus) registers the same /api route but the component lazy-loads the vendored, version-pinned bundle on first mount. Homepage JS/CSS payload drops ~2.6MB -> ~0.7MB uncompressed. Verified in-browser: no scalar reference on any other page, /api renders the full reference via the lazy load. - /guides/why-ferro/ retargeted at its query: title/description/opening now carry "LiteLLM alternative" / "Portkey replacement" language (every SERP competitor brands an alternatives page; ours had the content but zero keyword match). Sidebar label "Comparisons & Alternatives"; migration links promoted; "zero runtime dependencies" softened to "single static binary". - Homepage leads with the category: opening sentence now says "open-source, self-hosted AI gateway" (was buried mid-page), plus a production-readiness line (benchmarks, retries/breakers, probes) for the platform-lead persona.
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.
Summary
A full overhaul of docs.ferrolabs.ai for the v1.4.0/v1.4.1 gateway. An audit of all 36 pages against the v1.2.0–v1.4.1 changelog found 1 fresh, 17 stale, 18 wrong — every page was corrected against the
ai-gatewaysource, and the site was restructured into a cleaner, enterprise documentation experience.The whole thing was produced source-grounded: agents read the Go source (not prior docs) for every claim, and caught several real errors in the process (e.g.
budgetprices from operator-configured rates not the live catalog;single-mode open-circuit handling; the retry default normalizing to 1).Information architecture
/(slug/); the marketing landing page is removed and/intro/301s to/./plugins/*— plugin-system overview + one page per built-in plugin (word-filter, max-token, rate-limit, budget, response-cache, request-logger) + a Managed-plugins page. Replaces the singleguides/plugins./routing/*— routing overview + one page per strategy (single, fallback, loadbalance, least-latency, cost-optimized, conditional, content-based, ab-test). Replacesguides/routing-policies./providers(colored logo grid + endpoint-support matrix) and/providers/configuration(per-provider env vars). Replaces the threeguides/providers*pages./guides/dashboard— new page for the embedded v1.4.0 dashboard.guides/admin-authmerged intoguides/auth.static/_redirects(plus a client-redirect fallback); all internal links repointed to the new IA.Accuracy highlights (all v1.4.x-correct now)
insufficient_quota(was 429);/metricsrequires a scoped bearer;SkipProvider(removedContext.Skip); targets is an allowlist; retry honoured under every routing mode;FERRO_OLLAMA_MODELS;MASTER_KEY(removedADMIN_BOOTSTRAP_KEY); base-URL-verbatim rule; per-IP rate limit on by default; real OTel var surface;/livez+/readyz; MCP stdio transport.Design & SEO
static/img/providers/.src/data/product.tssingle source of product facts wired into the chrome — fixes the v1.0.0 / 29-providers / Go 1.24 drift across hero/footer/JSON-LD.lastmod+/searchexclusion, JSON-LD version bump,robots.txt+llms.txtrefresh.check-doc-accuracy.mjs: dropped the now-validmodel_prefixban, added anaccuracy-okescape and this audit's wrong-token denylist.Test plan
pnpm typecheckpnpm check:frontmatterpnpm check:docspnpm build(validates every internal link + anchor;onBrokenLinks: throw)_redirects301s resolve on the preview deploy