docs: comprehensive UX/UI improvements to homepage, navigation, and content by alexagriffith · Pull Request #658 · kserve/website

alexagriffith · 2026-04-14T22:38:10Z

Summary

This PR overhauls the documentation site's UX/UI across the homepage, navigation, sidebar, and key content pages. No existing content was removed — all changes are additive improvements (better layout, clearer naming, added links, improved visual hierarchy).

While updating the community page I noticed quite a few stylistic and naming inconsistencies and misalignments. so I kind of accidentally went down this rabbit hole of trying to make it all more consistent.

Changes by Area

Navigation & Sidebar

Merged standalone Blog link into Community dropdown
Moved nightly version dropdown to right-aligned position
Getting Started: grouped tutorial pages under a new collapsible "Deploy Your First" category with clearer labels (Serve an LLM, Serve an LLM (Advanced), Serve a Predictive Model)
Control Plane: restructured as a category with two distinct sub-items to surface the InferenceService vs LLMInferenceService distinction in the sidebar
Added link properties to Architecture, Generative Inference, and other categories so breadcrumb navigation clicks through correctly
Applied all sidebar changes to versioned sidebars (v0.16, v0.17)

Homepage

CTA buttons: consistent two-tone style (white Quickstart + dark navy Install) with equal fixed widths
Architecture cards: higher-contrast border/background in light mode
Benefits section: replaced long flat list with a tabbed layout (Generative AI / Predictive AI / Universal), each tab with linked feature rows
Section nav scroll: fixed scroll-spy offset to correctly account for combined navbar + section nav height
Quick Start code block: boosted syntax token contrast in light mode using a colorblind-safe palette (orange-brown for strings, dark teal for numbers — avoids red/green conflict)
New HomepageSectionNav component for smooth scroll-to-section navigation

Welcome to KServe (`intro.mdx`)

Converted intro.md → intro.mdx with full MDX layout: responsive grid cards, tabbed Key Benefits, tabbed Supported Frameworks grid with doc-card links
Every feature in the Key Benefits table now links to its relevant docs page (all three tabs)
All internal links use bare relative paths to avoid Docusaurus TabItem base-path resolution bug

Global CSS / Syntax Highlighting

Added doc-grid-2, doc-grid-3, doc-card responsive utility classes for MDX pages
Added light-mode syntax highlighting overrides (VS Code Default Light+ inspired, WCAG AA contrast, colorblind-safe): dark blue for keys/properties, orange-brown for strings, dark teal for numbers, slate for comments
Footer column alignment fix; search bar keyboard shortcut badges hidden on narrow screens

Content Improvements

install/overview.md: added "Which Installation Do I Need?" decision table at the top with three paths (KServe only → Predictive; KServe + LLMIsvc → GenAI; Full stack → caching)
control-plane.md: added InferenceService vs LLMInferenceService comparison table
control-plane-llmisvc.md: added intro paragraph explaining why this CRD exists and who should read it
genai-first-llmisvc.md: added "New to KServe?" info callout pointing new users to the simpler tutorial first
swagger-ui.md: added callout linking to full V1/V2 protocol documentation
v1-protocol.md, v2-protocol.md: standardized titles and sidebar_label frontmatter

Reviewer Notes

No content was deleted or should have been — all changes are layout, naming, linking, or additive context
The intro.md → intro.mdx rename is intentional: MDX is required for <Tabs>, <TabItem>, and JSX grid cards
Versioned docs (v0.16, v0.17) are left as frozen snapshots — only the sidebar navigation structure is updated
All internal links were manually verified against the sidebar doc IDs

Test plan

npm run build passes with no broken link warnings
Homepage renders correctly in light and dark mode
Sidebar "Deploy Your First" category collapses/expands correctly
Control Plane sub-items navigate to correct pages
Breadcrumb links on Architecture, Generative Inference categories work
All Key Benefits table links in intro.mdx resolve (no 404s)
Code block syntax colors readable in light mode; dark mode unchanged
Versioned docs (v0.16, v0.17) show updated sidebar structure

🤖 Generated with Claude Code

netlify · 2026-04-14T22:38:15Z

✅ Deploy Preview for elastic-nobel-0aef7a ready!

Name	Link
🔨 Latest commit	`1a9a433`
🔍 Latest deploy log	https://app.netlify.com/projects/elastic-nobel-0aef7a/deploys/69ded7f2aca8f70009122000
😎 Deploy Preview	https://deploy-preview-658--elastic-nobel-0aef7a.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

…ontent - Restructure navbar: standardize to "Getting Started" (was "Get Started"), reorganize Docs dropdown with grouped sections, merge Blog into Community - Rewrite homepage with improved hero, benefits, architecture, adopters, quickstart, and showcase sections; fix broken homepage links - Add HomepageSectionNav component for improved navigation - Create deploy-your-first.md decision guide with comparison table replacing broken generated-index description - Standardize tutorial page titles to "Deploy Your First LLM/Predictive..." naming scheme with (Standard)/(Advanced) clarity labels - Add colorblind-safe syntax highlighting in light mode (orange-brown strings, dark teal numbers, dark blue keys/attributes) - Add "Which Installation Do I Need?" decision table to install/overview.md - Update control-plane-llmisvc.md sidebar label and add purpose/audience intro - Add InferenceService vs LLMInferenceService comparison table to control-plane.md - Update versioned sidebars (0.16, 0.17) to match new Deploy Your First structure - Fix footer label: "Get Started" → "Getting Started" - Update Next Steps links across quickstart-guide.md and llmisvc-install.md to use new consistent page titles Signed-off-by: Alexa Griffith <agriffith96@gmail.com>

alexagriffith · 2026-04-14T23:24:18Z

Question - do we want to say LLM or generative, I changed the getting started to be consistent saying LLM, but I know there is nuance there...so we can change it.

… scope InferenceService covers predictive and standard LLM workloads, not just 'Standard & GenAI' which was ambiguous. LLMInferenceService is for advanced LLM-only features. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Alexa Griffith <agriffith96@gmail.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Alexa Griffith <agriffith96@gmail.com>

- GPU Acceleration → multi-node guide (not generic admin overview) - Autoscaling (GenAI) → generative inference autoscaling page - Intelligent Routing → custom transformer docs (predictor/transformer/explainer routing) - Cost Efficient → serverless/scale-to-zero guide Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Alexa Griffith <agriffith96@gmail.com>

Replace wall-of-prose with decision table, workload comparison, and structured best practices sections. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Alexa Griffith <agriffith96@gmail.com>

…ll content Add decision tables, section dividers, and structured headings without removing any existing content. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Alexa Griffith <agriffith96@gmail.com>

…ction Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Alexa Griffith <agriffith96@gmail.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Alexa Griffith <agriffith96@gmail.com>

These URLs resolve incorrectly in Docusaurus static builds. Replaced: - multi-node/multi-node -> llmisvc-overview (covers GPU/multi-node) - autoscaling/autoscaling -> llmisvc-configuration (covers autoscaling config) - custom-transformer/custom-transformer -> inferencegraph/overview (routing) - serverless/serverless -> kpa-autoscaler (scale-to-zero) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Alexa Griffith <agriffith96@gmail.com>

- GPU Acceleration -> LLMIsvc deployment guide (covers multi-node GPU orchestration) - Autoscaling (GenAI) -> KEDA autoscaler docs - Intelligent Routing -> control-plane (predictor/transformer/explainer architecture) - Cost Efficient -> KPA autoscaler (Knative scale-to-zero, unchanged) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Alexa Griffith <agriffith96@gmail.com>

sivanantha321 · 2026-04-15T06:59:35Z

The home page lacks details about llminferenceservice. hope we can add that.

I think the getting started is where that lives, the homepage has gen ai usage info

sivanantha321 · 2026-04-15T07:03:43Z

+}
+
+[data-theme='dark'] .navbar__title {
+  color: white !important;


Can we try not to use !importent if possible ?

sivanantha321 · 2026-04-15T07:10:26Z

-    #60a5fa 70%,
-    #93c5fd 100%
-  );
+  background:


IMO, the old hero banner looks better except the button design.

Old:

New:

btw, there is inconsistency between dark and light theme.

the button was what i was trying to fix

which inconsistency do you mean exactly? i was trying to fix the dark theme, but the buttons just kept staying the same, im not a FE so I may just be missing a style expectancy

And i changed the style like that intentionally, its a preference of style i guess, i like the new one but if we like the previous banner which I assume you mean the drop down naming? I moved community info to the left, and version of the website to the right as that seems a little less important to the docs than the community docs. let me know exactly what you think should change

sivanantha321 · 2026-04-15T07:22:28Z

Not sure if we should remove modelmesh docs as it is archived.

alexagriffith · 2026-04-15T14:24:26Z

Not sure if we should remove modelmesh docs as it is archived.

where do you see it archived? I see it in docs/admin-guide/modelmesh.md

terrytangyuan

It might be useful to take some screenshots of the improvements to help review

terrytangyuan · 2026-04-15T17:09:06Z

where do you see it archived? I see it in docs/admin-guide/modelmesh.md

Yes, we can remove modelmesh. I just archived all relevant repos yesterday.

alexagriffith force-pushed the docs/ux-ui-improvements-2025-04 branch 2 times, most recently from b6a345d to 08cc5a3 Compare April 14, 2026 23:06

alexagriffith force-pushed the docs/ux-ui-improvements-2025-04 branch from 064fa03 to b9d6f55 Compare April 14, 2026 23:18

alexagriffith and others added 11 commits April 14, 2026 19:36

docs: add TensorRT link to supported frameworks on homepage

797c027

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Alexa Griffith <agriffith96@gmail.com>

docs: use official NVIDIA TensorRT developer page instead of GitHub

3496888

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Alexa Griffith <agriffith96@gmail.com>

docs: update intro tagline to mention generative AI alongside LLMs

694402d

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Alexa Griffith <agriffith96@gmail.com>

docs: reformat admin guide overview for scannability

827cfed

Replace wall-of-prose with decision table, workload comparison, and structured best practices sections. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Alexa Griffith <agriffith96@gmail.com>

docs: add links to Predictor, Transformer, Explainer in data plane se…

3d1700a

…ction Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Alexa Griffith <agriffith96@gmail.com>

docs: improve ModelMesh 'when to use' callout with actionable guidance

e94ee20

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Alexa Griffith <agriffith96@gmail.com>

sivanantha321 reviewed Apr 15, 2026

View reviewed changes

terrytangyuan reviewed Apr 15, 2026

View reviewed changes

Conversation

alexagriffith commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes by Area

Navigation & Sidebar

Homepage

Welcome to KServe (intro.mdx)

Global CSS / Syntax Highlighting

Content Improvements

Reviewer Notes

Test plan

Uh oh!

netlify bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for elastic-nobel-0aef7a ready!

Uh oh!

alexagriffith commented Apr 14, 2026

Uh oh!

sivanantha321 Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

alexagriffith Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

sivanantha321 Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

sivanantha321 Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sivanantha321 Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

alexagriffith Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

alexagriffith Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

alexagriffith Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

sivanantha321 commented Apr 15, 2026

Uh oh!

alexagriffith commented Apr 15, 2026

Uh oh!

terrytangyuan left a comment

Choose a reason for hiding this comment

Uh oh!

terrytangyuan commented Apr 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

alexagriffith commented Apr 14, 2026 •

edited

Loading

Welcome to KServe (`intro.mdx`)

netlify bot commented Apr 14, 2026 •

edited

Loading

sivanantha321 Apr 15, 2026 •

edited

Loading