diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index ddaca51c9..24efa0b98 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -1,8 +1,19 @@
 name: Documentation
 
-on: 
+on:
   push:
     branches: [ main]
+    paths:
+      - 'docs/**'
+      - 'src/modelskill/**'
+  pull_request:
+    paths:
+      - 'docs/**'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
 
 jobs:
   build:
@@ -10,7 +21,7 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    
+
     - name: Set up uv
       uses: astral-sh/setup-uv@v6
       with:
@@ -19,14 +30,26 @@ jobs:
 
     - name: Install dependencies
       run: uv sync --group dev --group docs
-    
+
     - name: Build documentation
       run: |
         make docs
 
-    - name: Publish to GitHub Pages
-      uses: peaceiris/actions-gh-pages@v3.6.1
+    - name: Upload Pages artifact
+      if: github.event_name == 'push'
+      uses: actions/upload-pages-artifact@v3
       with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: docs/_site/
-      
+        path: docs/_site/
+
+  deploy:
+    if: github.event_name == 'push'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4