From 6952cfb4739dcd9dffae925a2dc93bb8a4333962 Mon Sep 17 00:00:00 2001
From: Erik Faulhaber <44124897+efaulhaber@users.noreply.github.com>
Date: Thu, 20 Aug 2026 20:08:18 +0200
Subject: [PATCH 1/3] Clear `out` directory after docs build

---
 docs/make.jl | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/make.jl b/docs/make.jl
index ee7d9f9c8e..c3ec12ed7f 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -145,5 +145,10 @@ makedocs(sitename="TrixiParticles.jl",
              "References" => "references.md"
          ])
 
+# Simulations in the doctests and literate tutorials generate VTK and other output files
+# in `docs/build/tutorials/out`.
+# Do not commit these files to `gh-pages` for every documentation preview.
+rm(joinpath("docs", "build", "tutorials", "out"); recursive=true, force=true)
+
 deploydocs(repo="github.com/trixi-framework/TrixiParticles.jl",
            devbranch="main", push_preview=true)

From 9f562a7dcafb9130abe5f11f9a81d1bd070d84ad Mon Sep 17 00:00:00 2001
From: Erik Faulhaber <44124897+efaulhaber@users.noreply.github.com>
Date: Thu, 20 Aug 2026 22:43:51 +0200
Subject: [PATCH 2/3] Add GitHub action to clean up stale docs previews

---
 .github/workflows/DocPreviewCleanup.yml | 33 +++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
 create mode 100644 .github/workflows/DocPreviewCleanup.yml

diff --git a/.github/workflows/DocPreviewCleanup.yml b/.github/workflows/DocPreviewCleanup.yml
new file mode 100644
index 0000000000..c69406114a
--- /dev/null
+++ b/.github/workflows/DocPreviewCleanup.yml
@@ -0,0 +1,33 @@
+name: Doc Preview Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+# Ensure that only one "Doc Preview Cleanup" workflow is force pushing at a time
+concurrency:
+  group: doc-preview-cleanup
+  cancel-in-progress: false
+
+jobs:
+  doc-preview-cleanup:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+      - name: Delete preview and history + push changes
+        run: |
+          if [ -d "${preview_dir}" ]; then
+              git config user.name "Documenter.jl"
+              git config user.email "documenter@juliadocs.github.io"
+              git rm -rf "${preview_dir}"
+              git commit -m "delete preview"
+              git branch gh-pages-new "$(echo "delete history" | git commit-tree "HEAD^{tree}")"
+              git push --force origin gh-pages-new:gh-pages
+          fi
+        env:
+          preview_dir: previews/PR${{ github.event.number }}

From 48f95c4fe6d444a52eb6b51422be585c6650c42f Mon Sep 17 00:00:00 2001
From: Erik Faulhaber <44124897+efaulhaber@users.noreply.github.com>
Date: Fri, 21 Aug 2026 10:38:27 +0200
Subject: [PATCH 3/3] Update checkout action

---
 .github/workflows/DocPreviewCleanup.yml | 2 +-
 docs/make.jl                            | 3 +--
 2 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/DocPreviewCleanup.yml b/.github/workflows/DocPreviewCleanup.yml
index c69406114a..6af7934d0f 100644
--- a/.github/workflows/DocPreviewCleanup.yml
+++ b/.github/workflows/DocPreviewCleanup.yml
@@ -16,7 +16,7 @@ jobs:
       contents: write
     steps:
       - name: Checkout gh-pages branch
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         with:
           ref: gh-pages
       - name: Delete preview and history + push changes
diff --git a/docs/make.jl b/docs/make.jl
index c3ec12ed7f..37290158c5 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -146,8 +146,7 @@ makedocs(sitename="TrixiParticles.jl",
          ])
 
 # Simulations in the doctests and literate tutorials generate VTK and other output files
-# in `docs/build/tutorials/out`.
-# Do not commit these files to `gh-pages` for every documentation preview.
+# in `docs/build/tutorials/out`. Do not commit these files to `gh-pages`.
 rm(joinpath("docs", "build", "tutorials", "out"); recursive=true, force=true)
 
 deploydocs(repo="github.com/trixi-framework/TrixiParticles.jl",