From 44a6dbfa53c8cf833a75c92ca0fce25c5a2be110 Mon Sep 17 00:00:00 2001
From: Zanie Blue <contact@zanie.dev>
Date: Sat, 3 Aug 2024 08:41:33 -0500
Subject: [PATCH] Improvements to the documentation (#5718)

---
 CONTRIBUTING.md                               |  4 +-
 STYLE.md                                      |  3 +-
 docs/concepts/projects.md                     |  4 +-
 docs/concepts/python-versions.md              | 45 ++++++-----
 docs/features.md                              |  7 +-
 docs/first-steps.md                           | 10 ++-
 docs/guides/install-python.md                 | 46 ++++++++++--
 .../guides/integration/alternative-indexes.md | 21 +++---
 docs/guides/integration/docker.md             |  4 +-
 docs/guides/projects.md                       | 10 ++-
 docs/guides/scripts.md                        | 40 +++++++---
 docs/guides/tools.md                          |  4 +-
 docs/index.md                                 | 45 ++++++-----
 docs/installation.md                          | 62 ++++++++--------
 docs/pip/compile.md                           | 48 ++++++------
 docs/pip/environments.md                      | 35 ++++-----
 docs/pip/inspection.md                        | 20 ++---
 docs/pip/packages.md                          | 74 +++++++++----------
 mkdocs.template.yml                           |  2 +-
 19 files changed, 275 insertions(+), 209 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c14969255..a38ce0fd6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -78,8 +78,8 @@ system
 ["nvidia-pyindex" on PyPI](https://pypi.org/project/nvidia-pyindex/)), which can even occur when
 just resolving requirements. To prevent this, there's a Docker container you can run commands in:
 
-```bash
-docker buildx build -t uv-builder -f builder.dockerfile --load .
+```console
+$ docker buildx build -t uv-builder -f builder.dockerfile --load .
 # Build for musl to avoid glibc errors, might not be required with your OS version
 cargo build --target x86_64-unknown-linux-musl --profile profiling
 docker run --rm -it -v $(pwd):/app uv-builder /app/target/x86_64-unknown-linux-musl/profiling/uv-dev resolve-many --cache-dir /app/cache-docker /app/scripts/popular_packages/pypi_10k_most_dependents.txt
diff --git a/STYLE.md b/STYLE.md
index a87eb1e94..259f70712 100644
--- a/STYLE.md
+++ b/STYLE.md
@@ -84,7 +84,8 @@ The documentation is divided into:
 
 1. All code blocks should have a language marker.
 1. When using `console` syntax, use `$` to indicate commands — everything else is output.
-1. Do not use the `bash` syntax when displaying command output.
+1. Never use the `bash` syntax when displaying command output.
+1. Prefer `console` with `$` prefixed commands over `bash`.
 1. Command output should rarely be included — it's hard to keep up to date.
 1. Use `title` for example files, e.g., `pyproject.toml`, `Dockerfile`, or `example.py`.
 
diff --git a/docs/concepts/projects.md b/docs/concepts/projects.md
index f350fca6c..f75b2ffea 100644
--- a/docs/concepts/projects.md
+++ b/docs/concepts/projects.md
@@ -152,10 +152,10 @@ command.
 The given command can be provided by the project environment or exist outside of it, e.g.:
 
 ```console
-# Presuming the project provides `example-cli`
+$ # Presuming the project provides `example-cli`
 $ uv run example-cli foo
 
-# Running a `bash` script that requires the project to be available
+$ # Running a `bash` script that requires the project to be available
 $ uv run bash scripts/foo.sh
 ```
 
diff --git a/docs/concepts/python-versions.md b/docs/concepts/python-versions.md
index 8a77ae43b..a2dc21ed4 100644
--- a/docs/concepts/python-versions.md
+++ b/docs/concepts/python-versions.md
@@ -22,8 +22,8 @@ installations and all other Python installations as _system_ Python installation
 A specific Python version can be requested with the `--python` flag in most uv commands. For
 example, when creating a virtual environment:
 
-```bash
-uv venv --python 3.11.6
+```console
+$ uv venv --python 3.11.6
 ```
 
 uv will ensure that Python 3.11.6 is available — downloading and installing it if necessary — then
@@ -60,28 +60,37 @@ uv bundles a list of downloadable CPython and PyPy distributions for macOS, Linu
 
 To install a Python version at a specific version:
 
-```bash
-uv python install 3.12.3
+```console
+$ uv python install 3.12.3
 ```
 
 To install the latest patch version:
 
-```bash
-uv python install 3.12
+```console
+$ uv python install 3.12
 ```
 
 To install a version that satisfies constraints:
 
-```bash
-uv python install '>=3.8,<3.10'
+```console
+$ uv python install '>=3.8,<3.10'
 ```
 
 To install multiple versions:
 
-```bash
-uv python install 3.9 3.10 3.11
+```console
+$ uv python install 3.9 3.10 3.11
 ```
 
+To install a specific implementation:
+
+```console
+$ uv python install pypy
+```
+
+All of the [Python version request](#requesting-a-version) formats are supported except those that
+are used for requesting local interpreters such as a file path.
+
 ## Project Python versions
 
 By default `uv python install` will verify that a managed Python version is installed or install the
@@ -101,28 +110,28 @@ invocations.
 
 To list installed and available Python versions:
 
-```bash
-uv python list
+```console
+$ uv python list
 ```
 
 By default, downloads for other platforms and old patch versions are hidden.
 
 To view all versions:
 
-```bash
-uv python list --all-versions
+```console
+$ uv python list --all-versions
 ```
 
 To view Python versions for other platforms:
 
-```bash
-uv python list --all-platforms
+```console
+$ uv python list --all-platforms
 ```
 
 To exclude downloads and only show installed Python versions:
 
-```bash
-uv python list --only-installed
+```console
+$ uv python list --only-installed
 ```
 
 ## Discovery of Python versions
diff --git a/docs/features.md b/docs/features.md
index 38f87da50..586d9031e 100644
--- a/docs/features.md
+++ b/docs/features.md
@@ -1,10 +1,9 @@
 # Features
 
-uv supports the full Python development experience — from installing Python and hacking on simple
+uv provides essential features for Python development — from installing Python and hacking on simple
 scripts to working on large projects that support multiple Python versions and platforms.
 
-uv's commands can be broken down into sections of discrete features, which can be used
-independently.
+uv's interface can be broken down into sections, which can be used independently or together.
 
 ## Python versions
 
@@ -87,7 +86,7 @@ See the documentation on [locking environments](./pip/compile.md) for details.
 
     These commands do not exactly implement the interfaces and behavior of the tools they are based on. The further you stray from common workflows, the more likely you are to encounter differences. Consult the [pip-compatibility guide](./pip/compatibility.md) for details.
 
-## Internal
+## Utility
 
 Managing and inspecting uv's state, such as the cache, storage directories, or performing a
 self-update:
diff --git a/docs/first-steps.md b/docs/first-steps.md
index cda5cc9bb..ef13bf478 100644
--- a/docs/first-steps.md
+++ b/docs/first-steps.md
@@ -2,11 +2,16 @@
 
 uv only provides a command-line interface and must be used from a terminal.
 
-After [installing uv](./installation.md), you can check that uv is installed by running the `uv`
+After [installing uv](./installation.md), you can check that uv is available by running the `uv`
 command:
 
 ```console
 $ uv
+An extremely fast Python package manager.
+
+Usage: uv [OPTIONS] <COMMAND>
+
+...
 ```
 
 You should see a help menu listing the available commands.
@@ -63,5 +68,4 @@ $ uv pip --version  # Can be used with a subcommand
 ## Next steps
 
 Now that you've confirmed uv is installed and know how to get help, check out an
-[overview of features](./features.md) or jump straight into the [guides](./guides/index.md) to start
-using uv.
+[overview of features](./features.md) or jump to the [guides](./guides/index.md) to start using uv.
diff --git a/docs/guides/install-python.md b/docs/guides/install-python.md
index 520d323e4..639cec2cb 100644
--- a/docs/guides/install-python.md
+++ b/docs/guides/install-python.md
@@ -8,14 +8,18 @@ also install and manage Python versions for you.
 
     uv will [automatically fetch Python versions](#automatic-python-downloads) as needed — you don't need to install Python to get started.
 
+<!-- TODO(zanieb): I don't love this heading. -->
+
+## Getting started
+
 To install the latest Python version:
 
 ```console
 $ uv python install
 ```
 
-This will install a uv managed Python version even if there is already a Python installation on your
-system.
+This will install a uv-managed Python version even if there is already a Python installation on your
+system. If you've previously installed Python with uv, a new version will not be installed.
 
 !!! note
 
@@ -35,6 +39,13 @@ To prevent uv from managing Python system-wide, provide the `--no-shim` option d
 
 Once Python is installed, it will be used by `uv` commands automatically.
 
+!!! important
+
+    When Python is installed by uv, it will not be available globally (i.e. via the `python` command).
+    Support for this feature is planned for a future release. In the meantime, use
+    [`uv run`](../guides/scripts.md#using-different-python-versions) or
+    [create and activate a virtual environment](../pip/environments.md) to use `python` directly.
+
 ## Installing a specific version
 
 To install a specific Python version:
@@ -43,6 +54,18 @@ To install a specific Python version:
 $ uv python install 3.12
 ```
 
+To install multiple Python versions:
+
+```console
+$ uv python install 3.11 3.12
+```
+
+To install an alternative Python implementation, e.g. PyPy:
+
+```
+$ uv python install pypy@3.12
+```
+
 See the [`python install`](../concepts/python-versions.md#installing-a-python-version) documentation
 for more details.
 
@@ -77,17 +100,28 @@ version if Python is not found:
 $ uv venv
 ```
 
+!!! tip
+
+    Automatic Python downloads can be [easily disabled](../concepts/python-versions.md#disabling-automatic-python-downloads) if you want more control over when Python is downloaded.
+
 <!-- TODO(zanieb): Restore when Python shim management is added
 Note that when an automatic Python installation occurs, the `python` command will not be added to the shell. Use `uv python install-shim` to ensure the `python` shim is installed.
 -->
 
 ## Using an existing Python installation
 
-uv will also use an existing Python installation if already present on your system. There is no
-configuration necessary for this behavior: uv will use the system Python if it satisfies the
-requirements of the command invocation. See the
-[Python discovery](../concepts/python-versions.md#discovery-order) documentation for details.
+uv will use existing Python installations if present on your system. There is no configuration
+necessary for this behavior: uv will use the system Python if it satisfies the requirements of the
+command invocation. See the [Python discovery](../concepts/python-versions.md#discovery-order)
+documentation for details.
 
 To force uv to use the system Python, provide the `--python-preference only-system` option. See the
 [Python version preference](../concepts/python-versions.md#adjusting-python-version-preferences)
 documentation for more details.
+
+## Next steps
+
+To learn more about `uv python`, see the [Python version concept](../concepts/python-versions.md)
+page and the [command reference](../reference/cli.md#uv-python).
+
+Or, read on to learn how to [run scripts](./scripts.md) and invoke Python with uv.
diff --git a/docs/guides/integration/alternative-indexes.md b/docs/guides/integration/alternative-indexes.md
index d30b6cf13..6526111bd 100644
--- a/docs/guides/integration/alternative-indexes.md
+++ b/docs/guides/integration/alternative-indexes.md
@@ -19,9 +19,10 @@ If there is a PAT available (eg
 credentials can be provided via the "Basic" HTTP authentication scheme. Include the PAT in the
 password field of the URL. A username must be included as well, but can be any string.
 
-```bash
-# With the token stored in the `ADO_PAT` environment variable
-export UV_EXTRA_INDEX_URL=https://dummy:$ADO_PAT@pkgs.dev.azure.com/{organisation}/{project}/_packaging/{feedName}/pypi/simple/
+For example, with the token stored in the `$ADO_PAT` environment variable, set the index URL with:
+
+```console
+$ export UV_EXTRA_INDEX_URL=https://dummy:$ADO_PAT@pkgs.dev.azure.com/{organisation}/{project}/_packaging/{feedName}/pypi/simple/
 ```
 
 ### Using `keyring`
@@ -44,15 +45,15 @@ The `keyring` executable must be in the `PATH`, i.e., installed globally or in t
 environment. The `keyring` CLI requires a username in the URL, so the index URL must include the
 default username `VssSessionToken`.
 
-```bash
-# Pre-install keyring and the Artifacts plugin from the public PyPI
-uv tool install keyring --with artifacts-keyring
+```console
+$ # Pre-install keyring and the Artifacts plugin from the public PyPI
+$ uv tool install keyring --with artifacts-keyring
 
-# Enable keyring authentication
-export UV_KEYRING_PROVIDER=subprocess
+$ # Enable keyring authentication
+$ export UV_KEYRING_PROVIDER=subprocess
 
-# Configure the index URL with the username
-export UV_EXTRA_INDEX_URL=https://VssSessionToken@pkgs.dev.azure.com/{organisation}/{project}/_packaging/{feedName}/pypi/simple/
+$ # Configure the index URL with the username
+$ export UV_EXTRA_INDEX_URL=https://VssSessionToken@pkgs.dev.azure.com/{organisation}/{project}/_packaging/{feedName}/pypi/simple/
 ```
 
 ## Other indexes
diff --git a/docs/guides/integration/docker.md b/docs/guides/integration/docker.md
index e821f830f..53560fb2a 100644
--- a/docs/guides/integration/docker.md
+++ b/docs/guides/integration/docker.md
@@ -5,8 +5,8 @@
 A Docker image is published with a built version of uv available. To run a uv command in a
 container:
 
-```bash
-docker run ghcr.io/astral-sh/uv --help
+```console
+$ docker run ghcr.io/astral-sh/uv --help
 ```
 
 ## Installing uv
diff --git a/docs/guides/projects.md b/docs/guides/projects.md
index dad7995ad..6422815ba 100644
--- a/docs/guides/projects.md
+++ b/docs/guides/projects.md
@@ -106,10 +106,10 @@ $ uv add requests
 You can also specify version constraints or alternative sources:
 
 ```console
-# Specify a version constraint
+$ # Specify a version constraint
 $ uv add 'requests==2.31.0'
 
-# Add a git dependency
+$ # Add a git dependency
 $ uv add requests --git https://github.com/psf/requests
 ```
 
@@ -166,5 +166,7 @@ See the documentation on [running commands](../concepts/projects.md#running-comm
 
 ## Next steps
 
-See the [projects concept](../concepts/projects.md) documentation for more details about working
-with projects.
+To learn more about working on projects with uv, see the [Projects concept](../concepts/projects.md)
+page and the [command reference](../reference/cli.md#uv).
+
+Or, read on to learn how to [run and install tools](./tools.md) with uv.
diff --git a/docs/guides/scripts.md b/docs/guides/scripts.md
index ba084ff03..e7a595033 100644
--- a/docs/guides/scripts.md
+++ b/docs/guides/scripts.md
@@ -1,8 +1,15 @@
 # Running scripts
 
 A Python script is a file intended for standalone execution, e.g., with `python <script>.py`. Using
-uv to execute scripts will ensure that script dependencies are properly managed inside and outside
-of projects.
+uv to execute scripts ensures that script dependencies are managed without manually managing
+environments.
+
+!!! note
+
+    If you are not familiar with Python environments: every Python installation has an environment
+    that packages can be installed in. Typically, creating [_virtual_ environments](https://docs.python.org/3/library/venv.html) is recommended to
+    isolate packages required by each script. uv automatically manages virtual environments for you
+    and prefers a [declarative](#declaring-script-dependencies) approach to dependencies.
 
 ## Running a script without dependencies
 
@@ -53,7 +60,7 @@ install the current project before running the script. If your script does not d
 project, use the `--no-project` flag to skip this:
 
 ```console
-# Note, it is important that the flag comes _before_ the script
+$ # Note, it is important that the flag comes _before_ the script
 $ uv run --no-project example.py
 ```
 
@@ -149,7 +156,11 @@ $ uv run example.py
 ]
 ```
 
-uv also supports Python version requirements:
+!!! important
+
+    When using inline script metadata, even if `uv run` is [used in a _project_](../concepts/projects.md#running-scripts), the project's dependencies will be ignored. The `--no-project` flag is not required.
+
+uv also respects Python version requirements:
 
 ```python title="example.py"
 # /// script
@@ -162,12 +173,13 @@ type Point = tuple[float, float]
 print(Point)
 ```
 
-uv will fetch the required Python version if it is not installed — see the documentation on
-[Python versions](../concepts/python-versions.md) for more details. Note that the `dependencies`
-field must be provided even if empty.
+!!! note
 
-Note that when using inline script metadata, even if `uv run` is used in a _project_, the project's
-dependencies will be ignored. The `--no-project` flag is not required.
+    The `dependencies` field must be provided even if empty.
+
+`uv run` will search for and use the required Python version. The Python version will download if it
+is not installed — see the documentation on [Python versions](../concepts/python-versions.md) for
+more details.
 
 ## Using different Python versions
 
@@ -180,16 +192,22 @@ print(".".join(map(str, sys.version_info[:3])))
 ```
 
 ```console
-# Use the default Python version, may differ on your machine
+$ # Use the default Python version, may differ on your machine
 $ uv run example.py
 3.12.1
 ```
 
 ```console
-# Use a specific Python version
+$ # Use a specific Python version
 $ uv run --python 3.10 example.py
 3.10.13
 ```
 
 See the [Python version request](../concepts/python-versions.md#requesting-a-version) documentation
 for more details on requesting Python versions.
+
+## Next steps
+
+To learn more about `uv run`, see the [command reference](../reference/cli.md#uv-run).
+
+Or, read on to learn how to to [work on projects](./projects.md).
diff --git a/docs/guides/tools.md b/docs/guides/tools.md
index 8bc2504a7..f18748143 100644
--- a/docs/guides/tools.md
+++ b/docs/guides/tools.md
@@ -151,5 +151,5 @@ $ uv tool install mkdocs --with mkdocs-material
 
 ## Next steps
 
-See the [tools concept](../concepts/tools.md) documentation for more details on how tools are
-managed.
+To learn more about managing tools with uv, see the [Tools concept](../concepts/projects.md) page
+and the [command reference](../reference/cli.md#uv-tool).
diff --git a/docs/index.md b/docs/index.md
index c945ace05..81f7b8ba4 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -35,20 +35,22 @@ uv is backed by [Astral](https://astral.sh), the creators of
 
 ## Getting started
 
-Install uv with our official standalone installer, on macOS and Linux:
+Install uv with our official standalone installer:
 
-```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh
+```console title="macOS and Linux"
+$ curl -LsSf https://astral.sh/uv/install.sh | sh
 ```
 
-Or, on Windows:
-
-```bash
-powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```console title="Windows"
+$ powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
 ```
 
-Then, check out the [first steps](./first-steps.md), see more
-[installation methods](./installation.md), or read on for a brief overview.
+Then, check out the [first steps](./first-steps.md) or read on for a brief overview.
+
+!!! tip
+
+    uv may also be installed with pip, Homebrew, and more. See all of the methods on the
+    [installation page](./installation.md).
 
 ## Project management
 
@@ -115,13 +117,12 @@ See the [tools guide](./guides/tools.md) to get started.
 
 ## Python management
 
-uv installs Python and allows quickly switching between Python versions.
+uv installs Python and allows quickly switching between versions.
 
-Install the Python versions your project requires:
+Install multiple Python versions:
 
 ```console
 $ uv python install 3.10 3.11 3.12
-warning: `uv python install` is experimental and may change without warning
 Searching for Python versions matching: Python 3.10
 Searching for Python versions matching: Python 3.11
 Searching for Python versions matching: Python 3.12
@@ -131,7 +132,7 @@ Installed 3 versions in 3.42s
  + cpython-3.12.4-macos-aarch64-none
 ```
 
-Or, fetch Python versions on demand:
+Download Python versions as needed:
 
 ```console
 $ uv venv --python 3.12.0
@@ -157,18 +158,16 @@ See the [installing Python guide](./guides/install-python.md) to get started.
 
 ## The pip interface
 
-uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands with
-support for a wide range of advanced `pip` features, including editable installs, Git dependencies,
-direct URL dependencies, local dependencies, constraints, source distributions, HTML and JSON
-indexes, and more.
-
-uv extends these interfaces with advanced features, such as dependency version overrides,
+uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands. uv
+extends their interfaces with advanced features, such as dependency version overrides,
 multi-platform resolutions, reproducible resolutions, alternative resolution strategies, and more.
 
 Compile requirements into a multi-platform requirements file:
 
 ```console
-$ uv pip compile docs/requirements.in --universal --output-file docs/requirements.txt
+$ uv pip compile docs/requirements.in \
+   --universal \
+   --output-file docs/requirements.txt
 Resolved 43 packages in 12ms
 ```
 
@@ -193,9 +192,9 @@ Installed 43 packages in 208ms
  ...
 ```
 
-See the [uv pip documentation](./pip/index.md) to get started.
+See the [pip interface documentation](./pip/index.md) to get started.
 
 ## Next steps
 
-See the [first steps](./first-steps.md) or jump straight into the [guides](./guides/index.md) to
-start using uv.
+See the [first steps](./first-steps.md) or jump straight to the [guides](./guides/index.md) to start
+using uv.
diff --git a/docs/installation.md b/docs/installation.md
index dd7ac0910..0459dfece 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -6,48 +6,50 @@ Install uv with our standalone installers, from PyPI, or from your package manag
 
 uv provides a standalone installer that downloads and installs uv:
 
-```bash
-# On macOS and Linux.
-curl -LsSf https://astral.sh/uv/install.sh | sh
+```console title="macOS and Linux"
+$ curl -LsSf https://astral.sh/uv/install.sh | sh
+```
 
-# On Windows.
-powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```console title="Windows"
+$ powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
 ```
 
 uv is installed to `~/.cargo/bin`.
 
 !!! tip
 
-    The installation script may be inspected with:
+    The installation script may be inspected before use:
 
-    ```bash
-    # On macOS and Linux.
-    curl -LsSf https://astral.sh/uv/install.sh | less
+    ```console title="macOS and Linux"
+    $ curl -LsSf https://astral.sh/uv/install.sh | less
+    ```
 
-    # On Windows.
-    powershell -c "irm https://astral.sh/uv/install.ps1 | more"
+    ```console title="Windows"
+    $ powershell -c "irm https://astral.sh/uv/install.ps1 | more"
     ```
 
     Alternatively, the installer or binaries can be downloaded directly from [GitHub](#github-releases).
 
-A specific release can be requested by including the version in the URL:
+Request a specific version by including it in the URL:
 
-```bash
-# On macOS and Linux.
-curl -LsSf https://astral.sh/uv/0.2.11/install.sh | sh
-
-# On Windows.
-powershell -c "irm https://astral.sh/uv/0.2.11/install.ps1 | iex"
+```console title="macOS and Linux"
+$ curl -LsSf https://astral.sh/uv/0.2.11/install.sh | sh
 ```
 
-When the standalone installer is used, uv can upgrade itself:
-
-```bash
-uv self update
+```console title="Windows"
+$ powershell -c "irm https://astral.sh/uv/0.2.11/install.ps1 | iex"
 ```
 
-When another installation method is used, self updates are disabled. Use the package manager's
-upgrade method instead.
+!!! tip
+
+    When the standalone installer is used, uv can perform self-updates:
+
+    ```console
+    $ uv self update
+    ```
+
+    When another installation method is used, self-updates are disabled. Use the package manager's
+    upgrade method instead.
 
 ## PyPI
 
@@ -55,14 +57,14 @@ For convenience, uv is published to [PyPI](https://pypi.org/project/uv/).
 
 If installing from PyPI, we recommend installing uv into an isolated environment, e.g., with `pipx`:
 
-```bash
-pipx install uv
+```console
+$ pipx install uv
 ```
 
 However, `pip` can also be used:
 
-```bash
-pip install uv
+```console
+$ pip install uv
 ```
 
 !!! note
@@ -76,8 +78,8 @@ pip install uv
 
 uv is available in the core Homebrew packages.
 
-```bash
-brew install uv
+```console
+$ brew install uv
 ```
 
 ## Docker
diff --git a/docs/pip/compile.md b/docs/pip/compile.md
index e57247a28..069e077f1 100644
--- a/docs/pip/compile.md
+++ b/docs/pip/compile.md
@@ -14,8 +14,8 @@ define dependencies.
 
 To lock dependencies declared in a `pyproject.toml`:
 
-```bash
-uv pip compile pyproject.toml -o requirements.txt
+```console
+$ uv pip compile pyproject.toml -o requirements.txt
 ```
 
 Note by default the `uv pip compile` output is just displayed and `--output-file` / `-o` argument is
@@ -23,39 +23,39 @@ needed to write to a file.
 
 To lock dependencies declared in a `requirements.in`:
 
-```bash
-uv pip compile requirements.in -o requirements.txt
+```console
+$ uv pip compile requirements.in -o requirements.txt
 ```
 
 To lock dependencies declared in multiple files:
 
-```bash
-uv pip compile pyproject.toml requirements-dev.in -o requirements-dev.txt`
+```console
+$ uv pip compile pyproject.toml requirements-dev.in -o requirements-dev.txt`
 ```
 
 uv also supports legacy `setup.py` and `setup.cfg` formats. To lock dependencies declared in a
 `setup.py`:
 
-```bash
-uv pip compile setup.py -o requirements.txt
+```console
+$ uv pip compile setup.py -o requirements.txt
 ```
 
 To lock dependencies from stdin, use `-`:
 
-```bash
-echo "ruff" | uv pip compile -
+```console
+$ echo "ruff" | uv pip compile -
 ```
 
 To lock with optional dependencies enabled, e.g., the "foo" extra:
 
-```bash
-uv pip install -r pyproject.toml --extra foo
+```console
+$ uv pip install -r pyproject.toml --extra foo
 ```
 
 To lock with all optional dependencies enabled:
 
-```bash
-uv pip install -r pyproject.toml --all-extras
+```console
+$ uv pip install -r pyproject.toml --all-extras
 ```
 
 Note extras are not supported with the `requirements.in` format.
@@ -75,8 +75,8 @@ ruff==0.3.0
 
 To upgrade a dependency, use the `--upgrade-package` flag:
 
-```bash
-uv pip compile - -o requirements.txt --upgrade-package ruff
+```console
+$ uv pip compile - -o requirements.txt --upgrade-package ruff
 ```
 
 To upgrade all dependencies, there is an `--upgrade` flag.
@@ -94,14 +94,14 @@ exactly matches the lockfile, use `uv pip sync` instead.
 
 To sync an environment with a `requirements.txt` file:
 
-```bash
-uv pip sync requirements.txt
+```console
+$ uv pip sync requirements.txt
 ```
 
 To sync an environment with a `pyproject.toml` file:
 
-```bash
-uv pip sync pyproject.toml
+```console
+$ uv pip sync pyproject.toml
 ```
 
 ## Adding constraints
@@ -119,8 +119,8 @@ pydantic<2.0
 
 To use a constraints file:
 
-```bash
-uv pip compile requirements.in --constraint constraints.txt
+```console
+$ uv pip compile requirements.in --constraint constraints.txt
 ```
 
 Note that multiple constraints can be defined in each file and multiple files can be used.
@@ -147,8 +147,8 @@ c>=2.0
 
 To use an overrides file:
 
-```bash
-uv pip compile requirements.in --override overrides.txt
+```console
+$ uv pip compile requirements.in --override overrides.txt
 ```
 
 Now, resolution can succeed. However, note that if `a` is _correct_ that it does not support
diff --git a/docs/pip/environments.md b/docs/pip/environments.md
index a68a0c01d..59b0b486e 100644
--- a/docs/pip/environments.md
+++ b/docs/pip/environments.md
@@ -9,25 +9,22 @@ installation's environment. Unlike `pip`, uv requires using a virtual environmen
 
 ## Creating a virtual environment
 
-uv supports creating virtual environments:
+uv supports creating virtual environments, e.g., to create a virtual environment at `.venv`:
 
-```bash
-# Create a virtual environment at `.venv`
-uv venv
+```console]
+$ uv venv
 ```
 
-A specific name or path can be specified:
+A specific name or path can be specified, e.g., to create a virtual environment at `my-name`:
 
-```bash
-# Create a virtual environment at `my-name`
-uv venv my-name
+```console
+$ uv venv my-name
 ```
 
-A Python version can be requested:
+A Python version can be requested, e.g., to create a virtual environment with Python 3.11:
 
-```bash
-# Create a virtual environment with Python 3.11
-uv venv --python 3.11
+```console
+$ uv venv --python 3.11
 ```
 
 Note this requires the requested Python version to be available on the system. However, if
@@ -39,8 +36,8 @@ documentation for more details.
 When using the default virtual environment name, uv will automatically find and use the virtual
 environment during subsequent invocations.
 
-```bash
-uv venv
+```console
+$ uv venv
 
 # Install a package in the new virtual environment
 uv pip install ruff
@@ -48,12 +45,12 @@ uv pip install ruff
 
 The virtual environment can be "activated" to make its packages available:
 
-```bash
-# On macOS and Linux.
-source .venv/bin/activate
+```console title="macOS and Linux"
+$ source .venv/bin/activate
+```
 
-# On Windows.
-.venv\Scripts\activate
+```console title="Windows"
+$ .venv\Scripts\activate
 ```
 
 ## Using arbitrary Python environments
diff --git a/docs/pip/inspection.md b/docs/pip/inspection.md
index 5dcd4071e..de2bea15b 100644
--- a/docs/pip/inspection.md
+++ b/docs/pip/inspection.md
@@ -4,28 +4,28 @@
 
 To list all of the packages in the environment:
 
-```bash
-uv pip list
+```console
+$ uv pip list
 ```
 
 To list the packages in a JSON format:
 
-```bash
-uv pip list --format json
+```console
+$ uv pip list --format json
 ```
 
 To list all of the packages in the environment in a `requirements.txt` format:
 
-```bash
-uv pip freeze
+```console
+$ uv pip freeze
 ```
 
 ## Inspecting a package
 
 To show information about an installed package, e.g., `numpy`:
 
-```bash
-uv pip show numpy
+```console
+$ uv pip show numpy
 ```
 
 Multiple packages can be inspected at once.
@@ -37,6 +37,6 @@ multiple steps.
 
 To check for conflicts or missing dependencies in the environment:
 
-```bash
-uv pip check
+```console
+$ uv pip check
 ```
diff --git a/docs/pip/packages.md b/docs/pip/packages.md
index fbb16174b..b6fd9995e 100644
--- a/docs/pip/packages.md
+++ b/docs/pip/packages.md
@@ -4,57 +4,57 @@
 
 To install a package into the virtual environment, e.g., Flask:
 
-```bash
-uv pip install flask
+```console
+$ uv pip install flask
 ```
 
 To install a package with optional dependencies enabled, e.g., Flask with the "dotenv" extra:
 
-```bash
-uv pip install "flask[dotenv]"
+```console
+$ uv pip install "flask[dotenv]"
 ```
 
 To install multiple packages, e.g., Flask and Ruff:
 
-```bash
-uv pip install flask ruff
+```console
+$ uv pip install flask ruff
 ```
 
 To install a package with a constraint, e.g., Ruff v0.2.0 or newer:
 
-```bash
-uv pip install 'ruff>=0.2.0'
+```console
+$ uv pip install 'ruff>=0.2.0'
 ```
 
 To install a package at a specific version, e.g., Ruff v0.3.0:
 
-```bash
-uv pip install 'ruff==0.3.0'
+```console
+$ uv pip install 'ruff==0.3.0'
 ```
 
 To install a package from the disk:
 
-```bash
-uv pip install "ruff @ ./projects/ruff"
+```console
+$ uv pip install "ruff @ ./projects/ruff"
 ```
 
 To install a package from GitHub:
 
-```bash
-uv pip install "git+https://github.com/astral-sh/ruff"
+```console
+$ uv pip install "git+https://github.com/astral-sh/ruff"
 ```
 
 To install a package from GitHub at a specific reference:
 
-```bash
-# Install a tag
-uv pip install "git+https://github.com/astral-sh/ruff@v0.2.0"
+```console
+$ # Install a tag
+$ uv pip install "git+https://github.com/astral-sh/ruff@v0.2.0"
 
-# Install a commit
-uv pip install "git+https://github.com/astral-sh/ruff@1fadefa67b26508cc59cf38e6130bde2243c929d"
+$ # Install a commit
+$ uv pip install "git+https://github.com/astral-sh/ruff@1fadefa67b26508cc59cf38e6130bde2243c929d"
 
-# Install a branch
-uv pip install "git+https://github.com/astral-sh/ruff@main"
+$ # Install a branch
+$ uv pip install "git+https://github.com/astral-sh/ruff@main"
 ```
 
 See the [Git authentication](../configuration/authentication.md#git-authentication) documentation
@@ -66,14 +66,14 @@ Editable packages do not need to be reinstalled for change to their source code
 
 To install the current project as an editable package
 
-```bash
-uv pip install -e .
+```console
+$ uv pip install -e .
 ```
 
 To install a project in another directory as an editable package:
 
-```bash
-uv pip install -e ruff @ ./project/ruff
+```console
+$ uv pip install -e ruff @ ./project/ruff
 ```
 
 ## Installing packages from files
@@ -82,8 +82,8 @@ Multiple packages can be installed at once from standard file formats.
 
 Install from a `requirements.txt` file:
 
-```bash
-uv pip install -r requirements.txt
+```console
+$ uv pip install -r requirements.txt
 ```
 
 See the [`uv pip compile`](./compile.md) documentation for more information on `requirements.txt`
@@ -91,32 +91,32 @@ files.
 
 Install from a `pyproject.toml` file:
 
-```bash
-uv pip install -r pyproject.toml
+```console
+$ uv pip install -r pyproject.toml
 ```
 
 Install from a `pyproject.toml` file with optional dependencies enabled, e.g., the "foo" extra:
 
-```bash
-uv pip install -r pyproject.toml --extra foo
+```console
+$ uv pip install -r pyproject.toml --extra foo
 ```
 
 Install from a `pyproject.toml` file with all optional dependencies enabled:
 
-```bash
-uv pip install -r pyproject.toml --all-extras
+```console
+$ uv pip install -r pyproject.toml --all-extras
 ```
 
 ## Uninstalling a package
 
 To uninstall a package, e.g., Flask:
 
-```bash
-uv pip uninstall flask
+```console
+$ uv pip uninstall flask
 ```
 
 To uninstall multiple packages, e.g., Flask and Ruff:
 
-```bash
-uv pip uninstall flask ruff
+```console
+$ uv pip uninstall flask ruff
 ```
diff --git a/mkdocs.template.yml b/mkdocs.template.yml
index ba80ef04f..a225032b1 100644
--- a/mkdocs.template.yml
+++ b/mkdocs.template.yml
@@ -89,8 +89,8 @@ nav:
       - guides/index.md
       - Installing Python: guides/install-python.md
       - Running scripts: guides/scripts.md
-      - Using tools: guides/tools.md
       - Working on projects: guides/projects.md
+      - Using tools: guides/tools.md
   - Concepts:
       - concepts/index.md
       - Projects: concepts/projects.md