diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index b2d596187..cd57ed263 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -3,6 +3,17 @@ name: Documentation
 on:
   push:
     branches: [ main]
+    paths:
+      - 'docs/**'
+      - 'src/modelskill/**'
+  pull_request:
+    paths:
+      - 'docs/**'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
 
 jobs:
   build:
@@ -26,12 +37,25 @@ jobs:
 
     - name: Install dependencies
       run: uv sync --group dev --group docs --group networks
-    
+
     - name: Build documentation
       run: just 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