Remove the configuration section in favor of concepts / reference (#13842)

Extends https://github.com/astral-sh/uv/pull/13841 — I'll drop that
commit later after that pull request merges but it's small.

I find the split into a "Configuration" section awkward and don't think
it's helping us. Everything moved into the "Concepts" section, except
the "Environment variables" page which definitely belongs in the
reference and the "Installer" page which is fairly niche and seems
better in the reference.

Before / After


<img
src="https://github.com/user-attachments/assets/80d8304b-17da-4900-a5f4-c3ccac96fcc5"
width="400">

.github/workflows/ci.yml

@@ -39,7 +39,7 @@ jobs:
 
           while IFS= read -r file; do
             # Generated markdown and JSON files are checked during test runs.
-            if [[ "${file}" =~ ^docs/ && ! "${file}" =~ ^docs/reference/(cli|settings).md && ! "${file}" =~ ^docs/configuration/environment.md ]]; then
+            if [[ "${file}" =~ ^docs/ && ! "${file}" =~ ^docs/reference/(cli|settings).md && ! "${file}" =~ ^docs/reference/environment.md ]]; then
               echo "Skipping ${file} (matches docs/ pattern)"
               continue
             fi

.prettierignore

@@ -3,6 +3,6 @@ CHANGELOG.md
 PREVIEW-CHANGELOG.md
 docs/reference/cli.md
 docs/reference/settings.md
-docs/configuration/environment.md
+docs/reference/environment.md
 ecosystem/home-assistant-core/LICENSE.md
 docs/guides/integration/gitlab.md

changelogs/0.4.x.md

@@ -960,7 +960,7 @@ argument (or the `UV_INDEX` environment variable); to replace the default index
 These changes are entirely backwards-compatible with the deprecated `--index-url` and
 `--extra-index-url` options, which continue to work as before.
 
-See the [Index](https://docs.astral.sh/uv/configuration/indexes/) documentation for more.
+See the [Index](https://docs.astral.sh/uv/concepts/indexes/) documentation for more.
 
 ### Enhancements
 

crates/uv-dev/src/generate_env_vars_reference.rs

@@ -21,7 +21,7 @@ pub(crate) fn main(args: &Args) -> anyhow::Result<()> {
     let filename = "environment.md";
     let reference_path = PathBuf::from(ROOT_DIR)
         .join("docs")
-        .join("configuration")
+        .join("reference")
         .join(filename);
 
     match args.mode {

docs/concepts/index.md

@@ -5,7 +5,11 @@ Read the concept documents to learn more about uv's features:
 - [Projects](./projects/index.md)
 - [Tools](./tools.md)
 - [Python versions](./python-versions.md)
+- [Configuration files](./configuration-files.md)
+- [Package indexes](./indexes.md)
 - [Resolution](./resolution.md)
+- [The uv build backend](./build-backend.md)
+- [Authentication](./authentication.md)
 - [Caching](./cache.md)
 - [The pip interface](../pip/index.md)
 

docs/concepts/projects/dependencies.md

@@ -42,7 +42,7 @@ field.
 
 The dependency will include a constraint, e.g., `>=0.27.2`, for the most recent, compatible version
 of the package. The kind of bound can be adjusted with
-[`--bounds`](../../reference/settings.md#bounds), or the constraint can be provided directly:
+[`--bounds`](../../reference/settings.md#add-bounds), or the constraint can be provided directly:
 
 ```console
 $ uv add "httpx>=0.20"

docs/concepts/python-versions.md

@@ -284,7 +284,7 @@ during `uv python install`.
 !!! tip
 
     The `python-downloads` setting can be set in a
-    [persistent configuration file](../configuration/files.md) to change the default behavior, or
+    [persistent configuration file](./configuration-files.md) to change the default behavior, or
     the `--no-python-downloads` flag can be passed to any uv command.
 
 ## Requiring or disabling managed Python versions

docs/configuration/index.md

@@ -1,12 +0,0 @@
-# Configuration overview
-
-Read about the various ways to configure uv:
-
-- [Using configuration files](./files.md)
-- [Using environment variables](./environment.md)
-- [Configuring authentication](./authentication.md)
-- [Configuring package indexes](./indexes.md)
-- [The uv build backend](build-backend.md)
-
-Or, jump to the [settings reference](../reference/settings.md) which enumerates the available
-configuration options.

docs/getting-started/installation.md

@@ -62,7 +62,7 @@ uv provides a standalone installer to download and install uv:
 
     Alternatively, the installer or binaries can be downloaded directly from [GitHub](#github-releases).
 
-See the documentation on [installer configuration](../configuration/installer.md) for details on
+See the reference documentation on the [installer](../reference/installer.md) for details on
 customizing your uv installation.
 
 ### PyPI

docs/guides/integration/alternative-indexes.md

@@ -8,8 +8,8 @@ description:
 # Using alternative package indexes
 
 While uv uses the official Python Package Index (PyPI) by default, it also supports
-[alternative package indexes](../../configuration/indexes.md). Most alternative indexes require
-various forms of authentication, which require some initial setup.
+[alternative package indexes](../../concepts/indexes.md). Most alternative indexes require various
+forms of authentication, which require some initial setup.
 
 !!! important
 

docs/guides/projects.md

@@ -87,8 +87,8 @@ description or license. You can edit this file manually, or use commands like `u
     See the official [`pyproject.toml` guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/)
     for more details on getting started with the `pyproject.toml` format.
 
-You'll also use this file to specify uv [configuration options](../configuration/files.md) in a
-[`[tool.uv]`](../reference/settings.md) section.
+You'll also use this file to specify uv [configuration options](../concepts/configuration-files.md)
+in a [`[tool.uv]`](../reference/settings.md) section.
 
 ### `.python-version`
 

docs/guides/scripts.md

@@ -252,8 +252,8 @@ print(httpx.get("https://example.com"))
 
 ## Using alternative package indexes
 
-If you wish to use an alternative [package index](../configuration/indexes.md) to resolve
-dependencies, you can provide the index with the `--index` option:
+If you wish to use an alternative [package index](../concepts/indexes.md) to resolve dependencies,
+you can provide the index with the `--index` option:
 
 ```console
 $ uv add --index "https://example.com/simple" --script example.py 'requests<3' 'rich'
@@ -267,7 +267,7 @@ This will include the package data in the inline metadata:
 ```
 
 If you require authentication to access the package index, then please refer to the
-[package index](../configuration/indexes.md) documentation.
+[package index](../concepts/indexes.md) documentation.
 
 ## Locking dependencies
 

docs/pip/compatibility.md

@@ -36,7 +36,7 @@ drawbacks:
 
 Instead, uv supports its own environment variables, like `UV_INDEX_URL`. uv also supports persistent
 configuration in a `uv.toml` file or a `[tool.uv.pip]` section of `pyproject.toml`. For more
-information, see [Configuration files](../configuration/files.md).
+information, see [Configuration files](../concepts/configuration-files.md).
 
 ## Pre-release compatibility
 
@@ -120,8 +120,8 @@ While `unsafe-best-match` is the closest to `pip`'s behavior, it exposes users t
 "dependency confusion" attacks.
 
 uv also supports pinning packages to dedicated indexes (see:
-[_Indexes_](../configuration/indexes.md#pinning-a-package-to-an-index)), such that a given package
-is _always_ installed from a specific index.
+[_Indexes_](../concepts/indexes.md#pinning-a-package-to-an-index)), such that a given package is
+_always_ installed from a specific index.
 
 ## PEP 517 build isolation
 

docs/pip/packages.md

@@ -57,8 +57,8 @@ $ # Install a branch
 $ uv pip install "git+https://github.com/astral-sh/ruff@main"
 ```
 
-See the [Git authentication](../configuration/authentication.md#git-authentication) documentation
-for installation from a private repository.
+See the [Git authentication](../concepts/authentication.md#git-authentication) documentation for
+installation from a private repository.
 
 ## Editable packages
 

docs/reference/installer.md

@@ -1,4 +1,4 @@
-# Configuring the uv installer
+# The uv installer
 
 ## Changing the install path
 

mkdocs.template.yml

@@ -74,6 +74,12 @@ plugins:
         "reference/versioning.md": "reference/policies/versioning.md"
         "reference/platforms.md": "reference/policies/platforms.md"
         "reference/build_failures.md": "reference/troubleshooting/build-failures.md"
+        "configuration/installer.md": "reference/installer.md"
+        "configuration/authentication.md": "concepts/authentication.md"
+        "configuration/build-backend.md": "concepts/build-backend.md"
+        "configuration/files.md": "concepts/configuration-files.md"
+        "configuration/indexes.md": "concepts/indexes.md"
+        "configuration/environment.md": "reference/environment.md"
 extra_css:
   - stylesheets/extra.css
 extra_javascript:
@@ -132,7 +138,11 @@ nav:
           - Using workspaces: concepts/projects/workspaces.md
       - Tools: concepts/tools.md
       - Python versions: concepts/python-versions.md
+      - Configuration files: concepts/configuration-files.md
+      - Package indexes: concepts/indexes.md
       - Resolution: concepts/resolution.md
+      - Build backend: concepts/build-backend.md
+      - Authentication: concepts/authentication.md
       - Caching: concepts/cache.md
       # Note:  The `pip` section was moved to the `concepts/` section but the
       # top-level directory structure was retained to ease the transition.
@@ -144,18 +154,12 @@ nav:
           - Declaring dependencies: pip/dependencies.md
           - Locking environments: pip/compile.md
           - Compatibility with pip: pip/compatibility.md
-  - Configuration:
-      - configuration/index.md
-      - Configuration files: configuration/files.md
-      - Environment variables: configuration/environment.md
-      - Authentication: configuration/authentication.md
-      - Package indexes: configuration/indexes.md
-      - Installer: configuration/installer.md
-      - Build backend: configuration/build-backend.md
   - Reference:
       - reference/index.md
       - Commands: reference/cli.md
       - Settings: reference/settings.md
+      - Environment variables: reference/environment.md
+      - Installer: reference/installer.md
       - Troubleshooting:
           - reference/troubleshooting/index.md
           - Build failures: reference/troubleshooting/build-failures.md

pyproject.toml

@@ -86,7 +86,7 @@ version_files = [
   "docs/guides/integration/pre-commit.md",
   "docs/guides/integration/github.md",
   "docs/guides/integration/aws-lambda.md",
-  "docs/configuration/build-backend.md",
+  "docs/concepts/build-backend.md",
 ]
 
 [tool.mypy]