[Docs] Improve docs search experience by limiting code block height in search results

[mgoin]

This fixes the issue where large code blocks would dominate the search modal, making it hard to scan through multiple results.

• Limit code blocks in search results to 8rem height with scroll
• Add fade-out gradient overlay for truncated content
• Limit overall search result item height to 20rem
• Add custom scrollbars for better UX
• Prevent very long lines from breaking search modal layout

[gemini-code-assist]

Code Review

This pull request improves the search experience by limiting the height of code blocks in search results. My review provides feedback to further enhance this by improving code readability, ensuring cross-browser compatibility for the new custom scrollbars, and increasing CSS maintainability. I've consolidated these points into a single comprehensive suggestion.

[gemini-code-assist]

There are a few areas for improvement in this new CSS for search results:

1. Code Readability: Using word-break: break-all can make code snippets unreadable by breaking identifiers and keywords. It's better to use overflow-x: auto to allow horizontal scrolling, which is a standard practice for code blocks and preserves readability.
2. Maintainability: The selector .md-search-result__article pre, .md-search-result__article .highlight is defined in two separate rules (lines 189-196 and 212-215). These should be combined into a single rule to improve maintainability.
3. Cross-browser Compatibility: The custom scrollbar styles (lines 230-251) are WebKit-specific. Support for Firefox should be added using the standard scrollbar-width and scrollbar-color properties for a consistent user experience.

Here is a suggested implementation that addresses all these points. It combines the duplicated rules, improves code readability by enabling horizontal scroll, and adds Firefox scrollbar support.

.md-search-result__article pre,
.md-search-result__article .highlight {
  position: relative;
  max-height: 8rem;
  overflow-y: auto;
  overflow-x: auto;
  border-radius: 0.2rem;
  margin: 0.5rem 0;
  scrollbar-width: thin;
  scrollbar-color: var(--md-default-fg-color--light) var(--md-default-fg-color--lightest);
}

/* Add fade-out gradient for truncated code blocks */
.md-search-result__article pre::after,
.md-search-result__article .highlight::after {
  content: "";
  position: absolute;
  bottom: 0;
  left: 0;
  right: 0;
  height: 1rem;
  background: linear-gradient(transparent, var(--md-default-bg-color));
  pointer-events: none;
}

[github-actions]

👋 Hi! Thank you for contributing to the vLLM project.

💬 Join our developer Slack at https://slack.vllm.ai to discuss your PR in #pr-reviews, coordinate on features in #feat- channels, or join special interest groups in #sig- channels.

Just a reminder: PRs would not trigger full CI run by default. Instead, it would only run fastcheck CI which starts running only a small and essential subset of CI tests to quickly catch errors. You can run other CI tests on top of those by going to your fastcheck build on Buildkite UI (linked in the PR checks section) and unblock them. If you do not have permission to unblock, ping simon-mo or khluu to add you in our Buildkite org.

Once the PR is approved and ready to go, your PR reviewer(s) can run CI to test the changes comprehensively before merging.

To run CI, PR reviewers can either: Add ready label to the PR or enable auto-merge.

🚀

[hmellor]

Another solution to this is to lower the search rank of large code blocks which we don't want to appear too near the top of search. (We already do this for the API docs)

Would this be something that could work instead? Or would you prefer to implement both solutions?

[hmellor]

For some reason RTD didn't pick this up and build it. I'm checking locally

[hmellor]

Screen.Recording.2025-07-30.at.16.24.06.mov