Migrate from MdBook to MkDocs (#5062)

## Summary

We want to have consistency between the Ruff and uv documentation for
the upcoming release. We don't love the Ruff docs, but we'd rather have
consistency and then work towards improving them both, rather than have
two very-different documentation sites that both have weaknesses.

The setup here is simpler than in Ruff as: (1) we don't yet generate any
docs from Rust and (2) we don't try to reuse the README in the uv
documentation (which adds a lot of complexity in Ruff). So the change
here is mostly a 1-to-1 port to MkDocs.

## Test Plan

![Screenshot 2024-07-14 at 9 49
15 PM](https://github.com/user-attachments/assets/8bfb5b06-08ff-4329-b368-d9087b78996e)

.github/workflows/docs.yml

@@ -1,49 +0,0 @@
-name: Publish documentation
-
-on:
-  push:
-    branches: ["main"]
-
-  # Allows you to run this workflow manually from the Actions tab
-  workflow_dispatch:
-
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
-concurrency:
-  group: "docs"
-  cancel-in-progress: false
-
-jobs:
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-      - name: Install latest mdbook
-        run: |
-          tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
-          url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
-          mkdir mdbook
-          curl -sSL $url | tar -xz --directory=./mdbook
-          echo `pwd`/mdbook >> $GITHUB_PATH
-      - name: Build mdbook
-        run: |
-          mdbook build docs
-      - name: Setup Pages
-        uses: actions/configure-pages@v5
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: "docs/book"
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4

.github/workflows/publish-docs.yml

@@ -0,0 +1,50 @@
+# Publish the uv documentation.
+#
+# Assumed to run as a subworkflow of .github/workflows/release.yml; specifically, as a post-announce
+# job within `cargo-dist`.
+name: mkdocs
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "The commit SHA, tag, or branch to publish. Uses the default branch if not specified."
+        default: ""
+        type: string
+
+jobs:
+  mkdocs:
+    runs-on: ubuntu-latest
+    env:
+      CF_API_TOKEN_EXISTS: ${{ secrets.CF_API_TOKEN != '' }}
+      MKDOCS_INSIDERS_SSH_KEY_EXISTS: ${{ secrets.MKDOCS_INSIDERS_SSH_KEY != '' }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.ref }}
+      - uses: actions/setup-python@v5
+      - name: "Add SSH key"
+        if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS == 'true' }}
+        uses: webfactory/ssh-agent@v0.9.0
+        with:
+          ssh-private-key: ${{ secrets.MKDOCS_INSIDERS_SSH_KEY }}
+      - name: "Install Insiders dependencies"
+        if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS == 'true' }}
+        run: pip install -r docs/requirements-insiders.txt
+      - name: "Install dependencies"
+        if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS != 'true' }}
+        run: pip install -r docs/requirements.txt
+      - name: "Build Insiders docs"
+        if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS == 'true' }}
+        run: mkdocs build --strict -f mkdocs.insiders.yml
+      - name: "Build docs"
+        if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS != 'true' }}
+        run: mkdocs build --strict -f mkdocs.public.yml
+      - name: "Deploy to Cloudflare Pages"
+        if: ${{ env.CF_API_TOKEN_EXISTS == 'true' }}
+        uses: cloudflare/wrangler-action@v3.7.0
+        with:
+          apiToken: ${{ secrets.CF_API_TOKEN }}
+          accountId: ${{ secrets.CF_ACCOUNT_ID }}
+          # `github.head_ref` is only set during pull requests and for manual runs or tags we use `main` to deploy to production
+          command: pages deploy site --project-name=uv-docs --branch ${{ github.head_ref || 'main' }} --commit-hash ${GITHUB_SHA}

docs/.overrides/partials/integrations/analytics/fathom.html

@@ -0,0 +1 @@
+<script src="https://cdn.usefathom.com/script.js" data-site="ESKBRHGN" defer></script>

docs/README.md

@@ -1,21 +0,0 @@
-# Documentation
-
-This is the home of the new documentation for uv.
-
-The documentation is a work in progress and not ready for external references.
-
-## Contributing
-
-Install mdbook:
-
-```
-cargo install mdbook
-```
-
-To run the documentation locally:
-
-```
-mdbook watch docs --open
-```
-
-The documentation is published to GitHub Pages on merge to `main`.

docs/SUMMARY.md

@@ -1,51 +0,0 @@
-# Summary
-
-- [Introduction](introduction.md)
-
-# Getting started
-
-- [Installing uv](installation.md)
-- [First steps](first-steps.md)
-
-# Guides
-
-- [Installing Python](guides/install-python.md)
-- [Running scripts](guides/scripts.md)
-- [Using tools](guides/tools.md)
-- [Creating a project](guides/projects.md)
-
-# Concepts
-
-- [Projects](preview/projects.md)
-- [Command-line tools](preview/tools.md)
-- [Python versions](python-versions.md)
-- [Workspaces](preview/workspaces.md)
-- [Dependency sources](preview/dependencies.md)
-- [Resolution](resolution.md)
-- [Caching](cache.md)
-- [Authentication](configuration/authentication.md)
-
-# Configuration
-
-- [Configuration files](configuration/files.md)
-- [Environment variables](configuration/environment.md)
-
-# Integration guides
-
-- [Using in Docker](guides/docker.md)
-- [Using in GitHub Actions](guides/github.md)
-- [Using in pre-commit](guides/pre-commit.md)
-
-# Low-level operations
-
-- [Using environments](pip/environments.md)
-- [Managing packages](pip/packages.md)
-- [Inspecting packages](pip/inspection.md)
-- [Declaring dependencies](pip/dependencies.md)
-- [Locking environments](pip/compile.md)
-
-# Policies
-
-- [Versioning](versioning.md)
-- [Platform support](platforms.md)
-- [Compatibility with pip](pip/compatibility.md)

docs/book.toml

@@ -1,9 +0,0 @@
-[book]
-language = "en"
-multilingual = false
-src = "."
-title = "uv"
-
-[output.html]
-no-section-label = true
-additional-css = ["style.css"]

docs/configuration/authentication.md

@@ -46,7 +46,7 @@ Authentication may be used for hosts specified in the following contexts:
 - `find-links`
 - `package @ https://...`
 
-See the [`pip` compatibility guide](./pip/compatibility.md#registry-authentication) for details on differences from
+See the [`pip` compatibility guide](../pip/compatibility.md#registry-authentication) for details on differences from
 `pip`.
 
 ## Custom CA certificates

docs/first-steps.md

@@ -33,7 +33,7 @@ These commands are used to manage Python itself. uv is capable of installing and
 - `uv python list`
 - `uv python find`
 
-See the documentation on [toolchains](./preview/toolchains.md) for more details on getting started.
+See the documentation on [toolchains](./python-versions.md) for more details on getting started.
 
 ### Command-line tool management
 

docs/guides/install-python.md

@@ -36,7 +36,7 @@ To view available and installed Python versions:
 $ uv python list
 ```
 
-See the [`python list`](../python-versions.html#viewing-available-python-versions) documentation for more details.
+See the [`python list`](../python-versions.md#viewing-available-python-versions) documentation for more details.
 
 <!--TODO(zanieb): The above should probably link to a CLI reference and that content should be moved out of that file -->
 
@@ -62,4 +62,4 @@ uv will also use an existing Python installation if already present on the syste
 
 To force uv to use the system Python, provide the `--python-preference only-system` option.
 
-See the [Python version preference](../python-versions.html#adjusting-python-version-preferences) documentation for more details.
+See the [Python version preference](../python-versions.md#adjusting-python-version-preferences) documentation for more details.

docs/index.md

@@ -9,11 +9,11 @@ An extremely fast Python package installer and resolver, written in Rust. Design
 replacement for common `pip` and `pip-tools` workflows.
 
 <p align="center">
-  <picture align="center">
-    <source media="(prefers-color-scheme: dark)" srcset="https://github.com/astral-sh/uv/assets/1309177/03aa9163-1c79-4a87-a31d-7a9311ed9310">
-    <source media="(prefers-color-scheme: light)" srcset="https://github.com/astral-sh/uv/assets/1309177/629e59c0-9c6e-4013-9ad4-adb2bcf5080d">
-    <img alt="Shows a bar chart with benchmark results." src="https://github.com/astral-sh/uv/assets/1309177/629e59c0-9c6e-4013-9ad4-adb2bcf5080d">
-  </picture>
+  <img alt="Shows a bar chart with benchmark results." src="{URL_LIGHT}#only-light">
+</p>
+
+<p align="center">
+  <img alt="Shows a bar chart with benchmark results." src="{URL_DARK}#only-dark">
 </p>
 
 <p align="center">
@@ -53,14 +53,14 @@ powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
 
 Or, see our [installation guide](./installation.md) for more options.
 
-Then, check out our documentation [creating an environment](pip/environments.html).
+Then, check out our documentation [creating an environment](pip/environments.md).
 
 ## Features
 
 uv supports features familiar from `pip` and `pip-tools`:
 
 - [Managing Python environments](pip/environments.md)
-- [Installing packages](pip/basics.md)
+- [Installing packages](pip/packages.md)
 - [Inspecting packages](pip/inspection.md)
 - [Locking environments](pip/compile.md)
 

docs/pip/compatibility.md

@@ -183,7 +183,7 @@ In other words, uv inverts the default, requiring explicit opt-in to installing
 Python, which can lead to breakages and other complications, and should only be done in limited
 circumstances.
 
-For more, see ["Installing into arbitrary Python environments"](./README.md#installing-into-arbitrary-python-environments).
+For more, see ["Using arbitrary Python environments"](./environments.md#using-arbitrary-python-environments).
 
 ## Resolution strategy
 

docs/pip/environments.md

@@ -26,8 +26,8 @@ uv venv --python 3.11
 ```
 
 Note this requires the requested Python version to be available on the system.
-However, in preview mode, [uv will download Python for you](../preview/toolchains.md).
-See the [python request](../python/requests.md) documentation for more details on requesting Python versions.
+However, in preview mode, [uv will download Python for you](../python-versions.md).
+See the [Python request](../python.md) documentation for more details on requesting Python versions.
 
 ## Using a virtual environment
 
@@ -115,4 +115,4 @@ If a specific Python version is requested, e.g., `--python 3.7`, additional exec
 
 When running a command that does not mutate the environment such as `uv pip compile`, uv does not
 _require_ a virtual environment. Instead, it needs a Python toolchain to create ephemeral environments.
-See the documentation on [toolchain discovery](./preview/toolchains.md#discovery-order) for details on discovery.
+See the documentation on [toolchain discovery](../python-versions.md#discovery-order) for details on discovery.

docs/preview/introduction.md

@@ -1,9 +0,0 @@
-# Introduction
-
-uv is expanding from low-level commands to manage virtual environments and their packages to high-level project management commands and global management of Python installations and command line tools.
-
-See the [project documentation](projects.md) for using uv to manage dependencies in a project, similar to `poetry`.
-
-See the [tool documentation](tools.md) for using uv to run tools in ephemeral environments and install tools, similar to `pipx`.
-
-See the [toolchain documentation](toolchains.md) for using uv to manage Python installations, similar to `pyenv`.

docs/python.md

@@ -1 +0,0 @@
-# Python environments

docs/requirements-insiders.in

@@ -0,0 +1,7 @@
+black>=23.10.0
+mkdocs>=1.5.0
+mkdocs-material @ git+ssh://git@github.com/astral-sh/mkdocs-material-insiders.git@38c0b8187325c3bab386b666daf3518ac036f2f4
+mkdocs-redirects>=1.2.1
+mdformat>=0.7.17
+mdformat-mkdocs>=2.0.4
+mdformat-admon>=2.0.2

docs/requirements-insiders.txt

@@ -0,0 +1,124 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile docs/requirements-insiders.in -o docs/requirements-insiders.txt --universal -p 3.12
+babel==2.15.0
+    # via mkdocs-material
+black==23.10.0
+    # via -r docs/requirements-insiders.in
+certifi==2024.7.4
+    # via requests
+charset-normalizer==3.3.2
+    # via requests
+click==8.1.7
+    # via
+    #   black
+    #   mkdocs
+colorama==0.4.6
+    # via
+    #   click
+    #   mkdocs
+    #   mkdocs-material
+ghp-import==2.1.0
+    # via mkdocs
+idna==3.7
+    # via requests
+jinja2==3.1.4
+    # via
+    #   mkdocs
+    #   mkdocs-material
+linkify-it-py==2.0.3
+    # via markdown-it-py
+markdown==3.6
+    # via
+    #   mkdocs
+    #   mkdocs-material
+    #   pymdown-extensions
+markdown-it-py==3.0.0
+    # via
+    #   mdformat
+    #   mdformat-gfm
+    #   mdit-py-plugins
+markupsafe==2.1.5
+    # via
+    #   jinja2
+    #   mkdocs
+mdformat==0.7.17
+    # via
+    #   -r docs/requirements-insiders.in
+    #   mdformat-admon
+    #   mdformat-gfm
+    #   mdformat-mkdocs
+    #   mdformat-tables
+mdformat-admon==2.0.2
+    # via
+    #   -r docs/requirements-insiders.in
+    #   mdformat-mkdocs
+mdformat-gfm==0.3.6
+    # via mdformat-mkdocs
+mdformat-mkdocs==2.0.4
+    # via -r docs/requirements-insiders.in
+mdformat-tables==0.4.1
+    # via mdformat-gfm
+mdit-py-plugins==0.4.1
+    # via
+    #   mdformat-admon
+    #   mdformat-gfm
+mdurl==0.1.2
+    # via markdown-it-py
+mergedeep==1.3.4
+    # via
+    #   mkdocs
+    #   mkdocs-material
+mkdocs==1.5.0
+    # via
+    #   -r docs/requirements-insiders.in
+    #   mkdocs-material
+    #   mkdocs-redirects
+mkdocs-material @ git+ssh://git@github.com/astral-sh/mkdocs-material-insiders.git@38c0b8187325c3bab386b666daf3518ac036f2f4
+    # via -r docs/requirements-insiders.in
+mkdocs-material-extensions==1.3.1
+    # via mkdocs-material
+mkdocs-redirects==1.2.1
+    # via -r docs/requirements-insiders.in
+more-itertools==10.3.0
+    # via mdformat-mkdocs
+mypy-extensions==1.0.0
+    # via black
+packaging==24.1
+    # via
+    #   black
+    #   mkdocs
+paginate==0.5.6
+    # via mkdocs-material
+pathspec==0.12.1
+    # via
+    #   black
+    #   mkdocs
+platformdirs==4.2.2
+    # via
+    #   black
+    #   mkdocs
+pygments==2.18.0
+    # via mkdocs-material
+pymdown-extensions==10.8.1
+    # via mkdocs-material
+python-dateutil==2.9.0.post0
+    # via ghp-import
+pyyaml==6.0.1
+    # via
+    #   mkdocs
+    #   pymdown-extensions
+    #   pyyaml-env-tag
+pyyaml-env-tag==0.1
+    # via mkdocs
+regex==2022.10.31
+    # via mkdocs-material
+requests==2.32.3
+    # via mkdocs-material
+six==1.16.0
+    # via python-dateutil
+uc-micro-py==1.0.3
+    # via linkify-it-py
+urllib3==2.2.2
+    # via requests
+watchdog==4.0.1
+    # via mkdocs

docs/requirements.in

@@ -0,0 +1,7 @@
+black>=23.10.0
+mkdocs>=1.5.0
+mkdocs-material>=9.1.18
+mkdocs-redirects>=1.2.1
+mdformat>=0.7.17
+mdformat-mkdocs>=2.0.4
+mdformat-admon>=2.0.2

docs/requirements.txt

@@ -0,0 +1,128 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile docs/requirements.in -o docs/requirements.txt --universal -p 3.12
+babel==2.15.0
+    # via mkdocs-material
+black==24.4.2
+    # via -r docs/requirements.in
+certifi==2024.7.4
+    # via requests
+charset-normalizer==3.3.2
+    # via requests
+click==8.1.7
+    # via
+    #   black
+    #   mkdocs
+colorama==0.4.6
+    # via
+    #   click
+    #   mkdocs
+    #   mkdocs-material
+ghp-import==2.1.0
+    # via mkdocs
+idna==3.7
+    # via requests
+jinja2==3.1.4
+    # via
+    #   mkdocs
+    #   mkdocs-material
+linkify-it-py==2.0.3
+    # via markdown-it-py
+markdown==3.6
+    # via
+    #   mkdocs
+    #   mkdocs-material
+    #   pymdown-extensions
+markdown-it-py==3.0.0
+    # via
+    #   mdformat
+    #   mdformat-gfm
+    #   mdit-py-plugins
+markupsafe==2.1.5
+    # via
+    #   jinja2
+    #   mkdocs
+mdformat==0.7.17
+    # via
+    #   -r docs/requirements.in
+    #   mdformat-admon
+    #   mdformat-gfm
+    #   mdformat-mkdocs
+    #   mdformat-tables
+mdformat-admon==2.0.6
+    # via
+    #   -r docs/requirements.in
+    #   mdformat-mkdocs
+mdformat-gfm==0.3.6
+    # via mdformat-mkdocs
+mdformat-mkdocs==3.0.0
+    # via -r docs/requirements.in
+mdformat-tables==0.4.1
+    # via mdformat-gfm
+mdit-py-plugins==0.4.1
+    # via
+    #   mdformat-admon
+    #   mdformat-gfm
+    #   mdformat-mkdocs
+mdurl==0.1.2
+    # via markdown-it-py
+mergedeep==1.3.4
+    # via
+    #   mkdocs
+    #   mkdocs-get-deps
+mkdocs==1.6.0
+    # via
+    #   -r docs/requirements.in
+    #   mkdocs-material
+    #   mkdocs-redirects
+mkdocs-get-deps==0.2.0
+    # via mkdocs
+mkdocs-material==9.5.29
+    # via -r docs/requirements.in
+mkdocs-material-extensions==1.3.1
+    # via mkdocs-material
+mkdocs-redirects==1.2.1
+    # via -r docs/requirements.in
+more-itertools==10.3.0
+    # via mdformat-mkdocs
+mypy-extensions==1.0.0
+    # via black
+packaging==24.1
+    # via
+    #   black
+    #   mkdocs
+paginate==0.5.6
+    # via mkdocs-material
+pathspec==0.12.1
+    # via
+    #   black
+    #   mkdocs
+platformdirs==4.2.2
+    # via
+    #   black
+    #   mkdocs-get-deps
+pygments==2.18.0
+    # via mkdocs-material
+pymdown-extensions==10.8.1
+    # via mkdocs-material
+python-dateutil==2.9.0.post0
+    # via ghp-import
+pyyaml==6.0.1
+    # via
+    #   mkdocs
+    #   mkdocs-get-deps
+    #   pymdown-extensions
+    #   pyyaml-env-tag
+pyyaml-env-tag==0.1
+    # via mkdocs
+regex==2024.5.15
+    # via mkdocs-material
+requests==2.32.3
+    # via mkdocs-material
+six==1.16.0
+    # via python-dateutil
+uc-micro-py==1.0.3
+    # via linkify-it-py
+urllib3==2.2.2
+    # via requests
+watchdog==4.0.1
+    # via mkdocs

docs/resolution.md

@@ -80,7 +80,7 @@ to model, and are a frequent source of bugs in other packaging tools. uv's pre-r
 is _intentionally_ limited and _intentionally_ requires user opt-in for pre-releases, to ensure
 correctness.
 
-For more, see ["Pre-release compatibility"](./PIP_COMPATIBILITY.md#pre-release-compatibility)
+For more, see ["Pre-release compatibility"](./pip/compatibility.md#pre-release-compatibility)
 
 ## Dependency overrides
 

docs/style.css

@@ -1,44 +0,0 @@
-/* Improve the font rendering */
-html {
-    font-family: -apple-system, BlinkMacSystemFont, Inter, Segoe UI, Helvetica Neue, sans-serif;
-}
-.heading, a, code, kbd, li, p, span, td {
-    -webkit-font-smoothing: antialiased;
-}
-
-/* Improve padding and display of the navbar */
-.chapter {
-    padding-inline-start: 1.2rem;
-}
-.chapter li.chapter-item {
-    margin-left: 1em;
-    margin-block-start: 0.2em;
-    font-weight: 300;
-    margin-block-end: 0.4em;
-    line-height: 1.2em;
-    font-size: 1.05em;
-}
-.chapter li.chapter-item a:hover {
-    text-decoration: underline;
-}
-.chapter li.part-title {
-    margin: 0 0 0 0;
-    font-weight: 500;
-    font-size: 1.3em;
-}
-
-/* Special case the landing page in the navbar */
-.chapter li.chapter-item:first-child {
-    margin-left: 0;
-    font-size: 16px
-}
-
-/* Hide the global title, it doesn't look good */
-.menu-title {
-    visibility: hidden;
-}
-
-/* Reduce spacing between sections in content */
-h2, h3 {
-    margin-block-start: 1.2em;
-}

docs/stylesheets/extra.css

@@ -0,0 +1,105 @@
+:root {
+  --black: #261230;
+  --white: #ffffff;
+  --radiate: #d7ff64;
+  --flare: #6340ac;
+  --rock: #78876e;
+  --galaxy: #261230;
+  --space: #30173d;
+  --comet: #6f5d6f;
+  --cosmic: #de5fe9;
+  --sun: #ffac2f;
+  --electron: #46ebe1;
+  --aurora: #46eb74;
+  --constellation: #5f6de9;
+  --neutron: #cff3cf;
+  --proton: #f6afbc;
+  --nebula: #cdcbfb;
+  --supernova: #f1aff6;
+  --starlight: #f4f4f1;
+  --lunar: #fbf2fc;
+  --asteroid: #e3cee3;
+  --crater: #f0dfdf;
+}
+
+[data-md-color-scheme="astral-light"] {
+  --md-default-bg-color--dark: var(--black);
+  --md-primary-fg-color: var(--galaxy);
+  --md-typeset-a-color: var(--flare);
+  --md-accent-fg-color: var(--cosmic);
+}
+
+[data-md-color-scheme="astral-dark"] {
+  --md-default-bg-color: var(--galaxy);
+  --md-default-fg-color: var(--white);
+  --md-default-fg-color--light: var(--white);
+  --md-default-fg-color--lighter: var(--white);
+  --md-primary-fg-color: var(--space);
+  --md-primary-bg-color: var(--white);
+  --md-accent-fg-color: var(--cosmic);
+
+  --md-typeset-color: var(--white);
+  --md-typeset-a-color: var(--radiate);
+  --md-typeset-mark-color: var(--sun);
+
+  --md-code-fg-color: var(--white);
+  --md-code-bg-color: var(--space);
+
+  --md-code-hl-comment-color: var(--asteroid);
+  --md-code-hl-punctuation-color: var(--asteroid);
+  --md-code-hl-generic-color: var(--supernova);
+  --md-code-hl-variable-color: var(--starlight);
+  --md-code-hl-string-color: var(--radiate);
+  --md-code-hl-keyword-color: var(--supernova);
+  --md-code-hl-operator-color: var(--supernova);
+  --md-code-hl-number-color: var(--electron);
+  --md-code-hl-special-color: var(--electron);
+  --md-code-hl-function-color: var(--neutron);
+  --md-code-hl-constant-color: var(--radiate);
+  --md-code-hl-name-color: var(--md-code-fg-color);
+
+  --md-typeset-del-color: hsla(6, 90%, 60%, 0.15);
+  --md-typeset-ins-color: hsla(150, 90%, 44%, 0.15);
+
+  --md-typeset-table-color: hsla(0, 0%, 100%, 0.12);
+  --md-typeset-table-color--light: hsla(0, 0%, 100%, 0.035);
+}
+
+[data-md-color-scheme="astral-light"] img[src$="#only-dark"],
+[data-md-color-scheme="astral-light"] img[src$="#gh-dark-mode-only"] {
+  display: none; /* Hide dark images in light mode */
+}
+
+[data-md-color-scheme="astral-light"] img[src$="#only-light"],
+[data-md-color-scheme="astral-light"] img[src$="#gh-light-mode-only"] {
+  display: inline; /* Show light images in light mode */
+}
+
+[data-md-color-scheme="astral-dark"] img[src$="#only-light"],
+[data-md-color-scheme="astral-dark"] img[src$="#gh-light-mode-only"] {
+  display: none; /* Hide light images in dark mode */
+}
+
+[data-md-color-scheme="astral-dark"] img[src$="#only-dark"],
+[data-md-color-scheme="astral-dark"] img[src$="#gh-dark-mode-only"] {
+  display: inline; /* Show dark images in dark mode */
+}
+
+/* See: https://github.com/squidfunk/mkdocs-material/issues/175#issuecomment-616694465 */
+.md-typeset__table {
+  min-width: 100%;
+}
+.md-typeset table:not([class]) {
+  display: table;
+}
+
+/* See: https://github.com/astral-sh/ruff/issues/8519 */
+[data-md-color-scheme="astral-dark"] details summary a {
+  color: var(--flare);
+}
+
+/* See: https://github.com/astral-sh/ruff/issues/9046 */
+[data-md-color-scheme="astral-dark"] div.admonition {
+  color: var(--md-code-fg-color);
+  background-color: var(--md-code-bg-color);
+}

mkdocs.insiders.yml

@@ -0,0 +1 @@
+INHERIT: mkdocs.template.yml

mkdocs.public.yml

@@ -0,0 +1,4 @@
+INHERIT: mkdocs.template.yml
+# Omit the `typeset` plugin which is only available in the Insiders version.
+plugins:
+  - search

mkdocs.template.yml

@@ -0,0 +1,105 @@
+site_name: uv
+theme:
+  name: material
+  favicon: assets/favicon.ico
+  features:
+    - navigation.instant
+    - navigation.instant.prefetch
+    - navigation.instant.progress
+    - navigation.expand
+    - navigation.tracking
+    - content.code.annotate
+    - toc.integrate
+    - toc.follow
+    - navigation.path
+    - navigation.top
+    - content.code.copy
+    - content.tabs.link
+  palette:
+    # Note: Using the system theme works with the insiders version
+    # https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#automatic-light-dark-mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: astral-light
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: astral-dark
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+  custom_dir: docs/.overrides
+repo_url: https://github.com/astral-sh/uv
+repo_name: uv
+site_author: charliermarsh
+site_url: https://docs.astral.sh/uv/
+site_dir: site/uv
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - toc:
+      permalink: "#"
+  - pymdownx.snippets:
+  - pymdownx.magiclink:
+  - attr_list:
+  - md_in_html:
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite:
+  - pymdownx.superfences:
+  - markdown.extensions.attr_list:
+  - pymdownx.keys:
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.tabbed:
+      alternate_style: true
+plugins:
+  - search
+  - typeset
+extra_css:
+  - stylesheets/extra.css
+extra:
+  analytics:
+    provider: fathom
+nav:
+  - Introduction: index.md
+  - Getting started:
+      - Installation: installation.md
+      - First steps: first-steps.md
+  - Guides:
+      - Installing Python: guides/install-python.md
+      - Running scripts: guides/scripts.md
+      - Using tools: guides/tools.md
+      - Creating a project: guides/projects.md
+  - Concepts:
+      - Projects: preview/projects.md
+      - Command-line tools: preview/tools.md
+      - Python versions: python-versions.md
+      - Workspaces: preview/workspaces.md
+      - Dependency sources: preview/dependencies.md
+      - Resolution: resolution.md
+      - Caching: cache.md
+      - Authentication: configuration/authentication.md
+  - Configuration:
+      - Configuration files: configuration/files.md
+      - Environment variables: configuration/environment.md
+  - Integration guides:
+      - Using in Docker: guides/docker.md
+      - Using in GitHub Actions: guides/github.md
+      - Using in pre-commit: guides/pre-commit.md
+  - Low-level operations:
+      - Using environments: pip/environments.md
+      - Managing packages: pip/packages.md
+      - Inspecting packages: pip/inspection.md
+      - Declaring dependencies: pip/dependencies.md
+      - Locking environments: pip/compile.md
+  - Policies:
+      - Versioning: versioning.md
+      - Platform support: platforms.md
+      - Compatibility with pip: pip/compatibility.md