astral-sh · zanieb · Jun 5, 2025 · Jun 4, 2025
diff --git a/.github/workflows/ci.yml b/.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

diff --git a/.prettierignore b/.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
diff --git a/changelogs/0.4.x.md b/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
 

diff --git a/crates/uv-dev/src/generate_env_vars_reference.rs b/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 {

diff --git a/docs/configuration/authentication.md → docs/concepts/authentication.md b/docs/configuration/authentication.md → docs/concepts/authentication.md
diff --git a/docs/configuration/build-backend.md → docs/concepts/build-backend.md b/docs/configuration/build-backend.md → docs/concepts/build-backend.md
diff --git a/docs/configuration/files.md → docs/concepts/configuration-files.md b/docs/configuration/files.md → docs/concepts/configuration-files.md
diff --git a/docs/concepts/index.md b/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)
 

diff --git a/docs/configuration/indexes.md → docs/concepts/indexes.md b/docs/configuration/indexes.md → docs/concepts/indexes.md
diff --git a/docs/concepts/projects/dependencies.md b/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"

diff --git a/docs/concepts/python-versions.md b/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

diff --git a/docs/configuration/index.md b/docs/configuration/index.md
diff --git a/docs/getting-started/installation.md b/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

diff --git a/docs/guides/integration/alternative-indexes.md b/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
 

diff --git a/docs/guides/projects.md b/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`
 

diff --git a/docs/guides/scripts.md b/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
 

diff --git a/docs/pip/compatibility.md b/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
 

diff --git a/docs/pip/packages.md b/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
 

diff --git a/docs/configuration/environment.md → docs/reference/environment.md b/docs/configuration/environment.md → docs/reference/environment.md
diff --git a/docs/configuration/installer.md → docs/reference/installer.md b/docs/configuration/installer.md → docs/reference/installer.md
@@ -1,4 +1,4 @@
-# Configuring the uv installer
+# The uv installer
 
 ## Changing the install path
 

diff --git a/mkdocs.template.yml b/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

diff --git a/pyproject.toml b/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]