Make distinct `code` and `console` admonitions so readers are less likely to miss them #20585

hmellor · 2025-07-07T16:54:47Z

Adds two new admonition types:

code
console

They have the colours of the question admonition (which we do not use) and each have their own icon.

This was done so that they are visually disinct from the default note admonition so users are more likely to notice them. It was noted in #19926 (comment) that the admonitions as they were could easily be missed.

cc @davidxia

…kely to miss them Signed-off-by: Harry Mellor <[email protected]>

github-actions · 2025-07-07T16:54:59Z

👋 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.

🚀

gemini-code-assist

Summary of Changes

Hello @hmellor, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the readability and clarity of the project's documentation by introducing new, visually distinct admonition types for code examples and console commands. The changes standardize the presentation of these critical information blocks, making it easier for users to quickly identify and understand them.

Highlights

New Admonition Types: Introduced two new admonition types, code and console, to visually differentiate code snippets and console commands within the documentation. This aims to make these important sections more noticeable to readers.
Enhanced Visual Styling: Defined distinct SVG icons and a consistent green color scheme (#64dd17) for the new code and console admonitions in docs/mkdocs/stylesheets/extra.css. This provides a clear visual cue, making them stand out from generic note admonitions.
Documentation Standardization: Applied the new code and console admonition types across a wide range of documentation files. This involved replacing various less specific admonition labels (e.g., Code, Command, Examples, Logs, Output, Response, Request, Config, Yaml, Json, CLI example, Dependency versions, note) to ensure consistent and improved presentation throughout the documentation.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces new code and console admonition types to improve the visual distinction of code blocks and console interactions in the documentation. The changes are applied consistently across a large number of markdown files. The implementation in CSS is also correct. I've provided feedback to improve consistency and code quality.

gemini-code-assist · 2025-07-07T16:57:30Z

docs/deployment/nginx.md

@@ -95,7 +95,7 @@ Notes:
 - The below example assumes GPU backend used. If you are using CPU backend, remove `--gpus device=ID`, add `VLLM_CPU_KVCACHE_SPACE` and `VLLM_CPU_OMP_THREADS_BIND` environment variables to the docker run command.
 - Adjust the model name that you want to use in your vLLM servers if you don't want to use `Llama-2-7b-chat-hf`.

-??? Commands
+??? console "Commands"

    ```console


This block contains an Nginx configuration snippet, which is a type of code. Using the code admonition would be more semantically correct and consistent with its usage in other parts of the documentation for configuration files.

Suggested change

```console

??? code "Command"

gemini-code-assist · 2025-07-07T16:57:31Z

docs/mkdocs/stylesheets/extra.css

+.md-typeset .admonition.code,
+.md-typeset details.code {
+  border-color: #64dd17
+}
+.md-typeset .admonition.console,
+.md-typeset details.console {
+  border-color: #64dd17
+}


The CSS rules for .admonition.code, details.code, .admonition.console, and details.console are identical. To improve maintainability and reduce code duplication, these selectors can be combined into a single rule.

.md-typeset .admonition.code, .md-typeset details.code, .md-typeset .admonition.console, .md-typeset details.console { border-color: #64dd17; }

gemini-code-assist · 2025-07-07T16:57:31Z

docs/mkdocs/stylesheets/extra.css

+.md-typeset .code > .admonition-title,
+.md-typeset .code > summary {
+  background-color: #64dd171a;
+}
+.md-typeset .console > .admonition-title,
+.md-typeset .console > summary {
+  background-color: #64dd171a;
+}


The CSS rules for the title and summary of code and console admonitions are identical. To improve maintainability and reduce code duplication, these selectors can be combined into a single rule.

.md-typeset .code > .admonition-title, .md-typeset .code > summary, .md-typeset .console > .admonition-title, .md-typeset .console > summary { background-color: #64dd171a; }

gemini-code-assist · 2025-07-07T16:57:31Z

docs/features/lora.md

@@ -172,7 +172,7 @@ Alternatively, follow these example steps to implement your own plugin:

 1. Implement the LoRAResolver interface.

-    ??? Example of a simple S3 LoRAResolver implementation
+    ??? code "Example of a simple S3 LoRAResolver implementation"


It's a code example, so it should be code instead of Example.

Suggested change

??? code "Example of a simple S3 LoRAResolver implementation"

??? code "Example of a simple S3 LoRAResolver implementation"

gemini-code-assist · 2025-07-07T16:57:31Z

docs/models/supported_models.md

@@ -642,7 +642,7 @@ Specified using `--task generate`.

    For the best results, we recommend using the following dependency versions (tested on A10 and L40):

-    ??? Dependency versions
+    ??? code "Dependency versions"


It's a code example, so it should be code instead of Dependency versions.

Suggested change

??? code "Dependency versions"

??? code "Dependency versions"

DarkLight1337 · 2025-07-08T02:55:19Z

This looks much better, thanks!

…kely to miss them (vllm-project#20585) Signed-off-by: Harry Mellor <[email protected]>

…kely to miss them (vllm-project#20585) Signed-off-by: Harry Mellor <[email protected]> Signed-off-by: Patrick von Platen <[email protected]>

…kely to miss them (vllm-project#20585) Signed-off-by: Harry Mellor <[email protected]>

…kely to miss them (vllm-project#20585) Signed-off-by: Harry Mellor <[email protected]> Signed-off-by: avigny <[email protected]>

…kely to miss them (vllm-project#20585) Signed-off-by: Harry Mellor <[email protected]>

Make distinct code and console admonitions so readers are less li…

e8a3e3d

…kely to miss them Signed-off-by: Harry Mellor <[email protected]>

mergify bot added documentation Improvements or additions to documentation structured-output tool-calling labels Jul 7, 2025

github-project-automation bot added this to Tool Calling and Structured Output Jul 7, 2025

gemini-code-assist bot reviewed Jul 7, 2025

View reviewed changes

hmellor mentioned this pull request Jul 7, 2025

[doc] Fold long code blocks to improve readability #19926

Merged

4 tasks

gemini-code-assist bot reviewed Jul 7, 2025

View reviewed changes

vllm-bot merged commit af107d5 into vllm-project:main Jul 8, 2025
16 checks passed

github-project-automation bot moved this to Done in Structured Output Jul 8, 2025

github-project-automation bot moved this to Done in Tool Calling Jul 8, 2025

hmellor deleted the distinct-code-console-admonitions branch July 8, 2025 07:03

huydhn pushed a commit to huydhn/vllm that referenced this pull request Jul 8, 2025

Make distinct code and console admonitions so readers are less li…

def4245

…kely to miss them (vllm-project#20585) Signed-off-by: Harry Mellor <[email protected]>

Chen-zexi pushed a commit to Chen-zexi/vllm that referenced this pull request Jul 13, 2025

Make distinct code and console admonitions so readers are less li…

ea3700e

…kely to miss them (vllm-project#20585) Signed-off-by: Harry Mellor <[email protected]>

LyrisZhong pushed a commit to LyrisZhong/vllm that referenced this pull request Jul 23, 2025

Make distinct code and console admonitions so readers are less li…

13b9138

…kely to miss them (vllm-project#20585) Signed-off-by: Harry Mellor <[email protected]>

avigny pushed a commit to avigny/vllm that referenced this pull request Jul 31, 2025

Make distinct code and console admonitions so readers are less li…

e5126b2

…kely to miss them (vllm-project#20585) Signed-off-by: Harry Mellor <[email protected]> Signed-off-by: avigny <[email protected]>

Pradyun92 pushed a commit to Pradyun92/vllm that referenced this pull request Aug 6, 2025

Make distinct code and console admonitions so readers are less li…

e1b948e

…kely to miss them (vllm-project#20585) Signed-off-by: Harry Mellor <[email protected]>

npanpaliya pushed a commit to odh-on-pz/vllm-upstream that referenced this pull request Aug 6, 2025

Make distinct code and console admonitions so readers are less li…

e84f064

…kely to miss them (vllm-project#20585) Signed-off-by: Harry Mellor <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Make distinct `code` and `console` admonitions so readers are less likely to miss them #20585

Make distinct `code` and `console` admonitions so readers are less likely to miss them #20585

Uh oh!

hmellor commented Jul 7, 2025 •

edited by github-actions bot

Loading

Uh oh!

github-actions bot commented Jul 7, 2025

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot Jul 7, 2025

Uh oh!

gemini-code-assist bot Jul 7, 2025

Uh oh!

gemini-code-assist bot Jul 7, 2025

Uh oh!

gemini-code-assist bot Jul 7, 2025

Uh oh!

gemini-code-assist bot Jul 7, 2025

Uh oh!

DarkLight1337 commented Jul 8, 2025

Uh oh!

Uh oh!

Uh oh!

	??? code "Example of a simple S3 LoRAResolver implementation"
	??? code "Example of a simple S3 LoRAResolver implementation"

	??? code "Dependency versions"
	??? code "Dependency versions"

Uh oh!

Make distinct code and console admonitions so readers are less likely to miss them #20585

Make distinct code and console admonitions so readers are less likely to miss them #20585

Uh oh!

Conversation

hmellor commented Jul 7, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jul 7, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

DarkLight1337 commented Jul 8, 2025

Uh oh!

Uh oh!

Uh oh!

Make distinct `code` and `console` admonitions so readers are less likely to miss them #20585

Make distinct `code` and `console` admonitions so readers are less likely to miss them #20585

hmellor commented Jul 7, 2025 •

edited by github-actions bot

Loading