diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index 9346c527a5..58969ed587 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -271,4 +271,4 @@ jobs:
       - name: "Check docs formatting"
         run: python scripts/check_docs_formatted.py
       - name: "Build docs"
-        run: mkdocs build --strict
+        run: mkdocs build --strict -f mkdocs.generated.yml
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
index 27f3bacd7d..56774ee991 100644
--- a/.github/workflows/docs.yaml
+++ b/.github/workflows/docs.yaml
@@ -26,7 +26,7 @@ jobs:
         run: |
           python scripts/transform_readme.py --target mkdocs
           python scripts/generate_mkdocs.py
-          mkdocs build --strict
+          mkdocs build --strict -f mkdocs.generated.yml
       - name: "Deploy to Cloudflare Pages"
         if: ${{ env.CF_API_TOKEN_EXISTS == 'true' }}
         uses: cloudflare/wrangler-action@2.0.0
diff --git a/.gitignore b/.gitignore
index 57a5b8f8ce..5bfce3449a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,8 +1,7 @@
 # Benchmarking cpython (CONTRIBUTING.md)
 crates/ruff/resources/test/cpython
 # generate_mkdocs.py
-mkdocs.yml
-.overrides
+mkdocs.generated.yml
 # check_ecosystem.py
 ruff-old
 github_search*.jsonl
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 153b43fa39..efd43b4c7e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -256,7 +256,7 @@ To preview any changes to the documentation locally:
 1. Run the development server with:
 
    ```shell
-   mkdocs serve
+   mkdocs serve -f mkdocs.generated.yml
    ```
 
 The documentation should then be available locally at
diff --git a/README.md b/README.md
index f333191ea2..b488d61eac 100644
--- a/README.md
+++ b/README.md
@@ -34,7 +34,8 @@ An extremely fast Python linter, written in Rust.
 - ⚖️ [Near-parity](https://beta.ruff.rs/docs/faq/#how-does-ruff-compare-to-flake8) with the
   built-in Flake8 rule set
 - 🔌 Native re-implementations of dozens of Flake8 plugins, like flake8-bugbear
-- ⌨️ First-party editor integrations for [VS Code](https://github.com/astral-sh/ruff-vscode) and [more](https://github.com/astral-sh/ruff-lsp)
+- ⌨️ First-party [editor integrations](https://beta.ruff.rs/docs/editor-integrations/) for
+  [VS Code](https://github.com/astral-sh/ruff-vscode) and [more](https://github.com/astral-sh/ruff-lsp)
 - 🌎 Monorepo-friendly, with [hierarchical and cascading configuration](https://beta.ruff.rs/docs/configuration/#pyprojecttoml-discovery)
 
 Ruff aims to be orders of magnitude faster than alternative tools while integrating more
diff --git a/docs/.overrides/partials/integrations/analytics/fathom.html b/docs/.overrides/partials/integrations/analytics/fathom.html
new file mode 100644
index 0000000000..340d60d816
--- /dev/null
+++ b/docs/.overrides/partials/integrations/analytics/fathom.html
@@ -0,0 +1 @@
+<script src="https://cdn.usefathom.com/script.js" data-site="DUAEBFLB" defer></script>
diff --git a/mkdocs.template.yml b/mkdocs.template.yml
index ec7dab6ced..761c36be23 100644
--- a/mkdocs.template.yml
+++ b/mkdocs.template.yml
@@ -23,7 +23,7 @@ theme:
       toggle:
         icon: material/weather-night
         name: Switch to light mode
-  custom_dir: .overrides
+  custom_dir: docs/.overrides
 repo_url: https://github.com/astral-sh/ruff
 repo_name: ruff
 site_author: charliermarsh
@@ -50,3 +50,6 @@ plugins:
   - search
 extra_css:
   - stylesheets/extra.css
+extra:
+  analytics:
+    provider: fathom
diff --git a/scripts/generate_mkdocs.py b/scripts/generate_mkdocs.py
index 8d0b92b882..f6954b153a 100644
--- a/scripts/generate_mkdocs.py
+++ b/scripts/generate_mkdocs.py
@@ -32,10 +32,6 @@ SECTIONS: list[Section] = [
     Section("Contributing", "contributing.md", generated=True),
 ]
 
-FATHOM_SCRIPT: str = (
-    '<script src="https://cdn.usefathom.com/script.js" data-site="DUAEBFLB" defer>'
-    "</script>"
-)
 
 LINK_REWRITES: dict[str, str] = {
     "https://beta.ruff.rs/docs/": "index.md",
@@ -45,7 +41,6 @@ LINK_REWRITES: dict[str, str] = {
     ),
     "https://beta.ruff.rs/docs/contributing/": "contributing.md",
     "https://beta.ruff.rs/docs/editor-integrations/": "editor-integrations.md",
-    "https://beta.ruff.rs/docs/faq/": "faq.md",
     "https://beta.ruff.rs/docs/faq/#how-does-ruff-compare-to-flake8": (
         "faq.md#how-does-ruff-compare-to-flake8"
     ),
@@ -53,7 +48,6 @@ LINK_REWRITES: dict[str, str] = {
     "https://beta.ruff.rs/docs/rules/": "rules.md",
     "https://beta.ruff.rs/docs/rules/#error-e": "rules.md#error-e",
     "https://beta.ruff.rs/docs/settings/": "settings.md",
-    "https://beta.ruff.rs/docs/usage/": "usage.md",
 }
 
 
@@ -92,7 +86,13 @@ def main() -> None:
 
     # Rewrite links to the documentation.
     for src, dst in LINK_REWRITES.items():
-        content = content.replace(f"({src})", f"({dst})")
+        before = content
+        after = content.replace(f"({src})", f"({dst})")
+        if before == after:
+            msg = f"Unexpected link rewrite in README.md: {src}"
+            raise ValueError(msg)
+        content = after
+
     if m := re.search(r"\(https://beta.ruff.rs/docs/.*\)", content):
         msg = f"Unexpected absolute link to documentation: {m.group(0)}"
         raise ValueError(msg)
@@ -140,18 +140,8 @@ def main() -> None:
     with Path("mkdocs.template.yml").open(encoding="utf8") as fp:
         config = yaml.safe_load(fp)
     config["nav"] = [{section.title: section.filename} for section in SECTIONS]
-    config["extra"] = {"analytics": {"provider": "fathom"}}
 
-    Path(".overrides/partials/integrations/analytics").mkdir(
-        parents=True,
-        exist_ok=True,
-    )
-    with Path(".overrides/partials/integrations/analytics/fathom.html").open(
-        "w+",
-    ) as fp:
-        fp.write(FATHOM_SCRIPT)
-
-    with Path("mkdocs.yml").open("w+") as fp:
+    with Path("mkdocs.generated.yml").open("w+") as fp:
         yaml.safe_dump(config, fp)