From 4f3ff797361a7a1d953353d90fd809d54469267f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= <tiangolo@gmail.com>
Date: Sun, 23 Nov 2025 09:41:43 -0800
Subject: [PATCH] =?UTF-8?q?=F0=9F=91=B7=20Add=20pre-commit=20config=20with?=
 =?UTF-8?q?=20local=20script=20for=20permalinks=20(#14398)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
---
 .github/workflows/pre-commit.yml |  7 +++++--
 .gitignore                       |  3 +++
 .pre-commit-config.yaml          | 29 +++++++++++++++++++----------
 requirements.txt                 |  2 +-
 scripts/docs.py                  |  9 +++++++++
 5 files changed, 37 insertions(+), 13 deletions(-)

diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml
index 838764057..fa0574d7d 100644
--- a/.github/workflows/pre-commit.yml
+++ b/.github/workflows/pre-commit.yml
@@ -7,7 +7,6 @@ on:
       - synchronize
 
 env:
-  UV_SYSTEM_PYTHON: 1
   IS_FORK: ${{ github.event.pull_request.head.repo.full_name != github.repository }}
 
 jobs:
@@ -41,6 +40,10 @@ jobs:
             requirements**.txt
             pyproject.toml
             uv.lock
+      - name: Install Dependencies
+        run: |
+          uv venv
+          uv pip install -r requirements.txt
       - name: Run pre-commit
         id: precommit
         run: |
@@ -69,7 +72,7 @@ jobs:
         run: exit 1
 
   # https://github.com/marketplace/actions/alls-green#why
-  alls-green:  # This job does nothing and is only used for the branch protection
+  pre-commit-alls-green:  # This job does nothing and is only used for the branch protection
     if: always()
     needs:
       - pre-commit
diff --git a/.gitignore b/.gitignore
index ef6364a9a..6016ffa59 100644
--- a/.gitignore
+++ b/.gitignore
@@ -28,3 +28,6 @@ archive.zip
 
 # macOS
 .DS_Store
+
+# Ignore while the setup still depends on requirements.txt files
+uv.lock
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index cc3d93779..8e6d93fb7 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,20 +1,29 @@
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
--   repo: https://github.com/pre-commit/pre-commit-hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
     hooks:
-    -   id: check-added-large-files
-    -   id: check-toml
-    -   id: check-yaml
+      - id: check-added-large-files
+      - id: check-toml
+      - id: check-yaml
         args:
-        -   --unsafe
-    -   id: end-of-file-fixer
-    -   id: trailing-whitespace
--   repo: https://github.com/astral-sh/ruff-pre-commit
+        - --unsafe
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+  - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.14.3
     hooks:
-    -   id: ruff
+      - id: ruff
         args:
         - --fix
-    -   id: ruff-format
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: local-script
+        language: unsupported
+        name: local script
+        entry: uv run ./scripts/docs.py add-permalinks-pages
+        args:
+          - --update-existing
+        files: ^docs/en/docs/.*\.md$
diff --git a/requirements.txt b/requirements.txt
index 9180bf1be..5d9f97b75 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,6 +1,6 @@
 -e .[all]
 -r requirements-tests.txt
 -r requirements-docs.txt
-pre-commit >=2.17.0,<5.0.0
+pre-commit >=4.5.0,<5.0.0
 # For generating screenshots
 playwright
diff --git a/scripts/docs.py b/scripts/docs.py
index d67ab50f7..73f60e68c 100644
--- a/scripts/docs.py
+++ b/scripts/docs.py
@@ -520,6 +520,15 @@ def add_permalinks_page(path: Path, update_existing: bool = False):
         f.writelines(updated_lines)
 
 
+@app.command()
+def add_permalinks_pages(pages: List[Path], update_existing: bool = False) -> None:
+    """
+    Add or update header permalinks in specific pages of En docs.
+    """
+    for md_file in pages:
+        add_permalinks_page(md_file, update_existing=update_existing)
+
+
 @app.command()
 def add_permalinks(update_existing: bool = False) -> None:
     """