diff --git a/.github/workflows/docs-preview-build.yml b/.github/workflows/docs-preview-build.yml
new file mode 100644
index 0000000000..cd3a6a6752
--- /dev/null
+++ b/.github/workflows/docs-preview-build.yml
@@ -0,0 +1,55 @@
+
+# This action builds and deploys the docs on each pull request created
+# Security notes:
+# The preview deployment is split in two workflows, preview_build and preview_deploy.
+# `preview_build` runs on pull_request, so it won't have any access to the repositories secrets, so it is safe to
+# build / execute untrusted code.
+# `preview_deploy` has access to the repositories secrets (so it can push to the pr preview repo) but won't run
+# any untrusted code (it will just extract the build artifact and push it to the pages branch where it will
+# automatically be deployed).
+
+# TODO: rewrite the comment and clarify
+
+# TODO: use commit hashes for actions
+
+# TODO: the publish job should run sequentially so that it does proper version switcher generation?
+
+name: Docs - preview build
+
+on:
+  - pull_request
+  
+# TODO: trailing whitespace
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+      
+      - name: Install uv
+        uses: astral-sh/setup-uv@2e657c127d5b1635d5a8e3fa40e0ac50a5bf6992
+        
+      - name: Build the docs
+        # Intentionally without --strict, to have previews even if the docs are
+        # mildly broken
+        run: uv run mkdocs build  
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: rendered-docs
+          path: rendered-docs
+
+      # TODO: this should indicate forks in the name, maybe? PR numbers are
+      # unique but pr_branch is not I suppose
+      - name: Generate meta.json
+        env:
+          PR_NUMBER: ${{ github.event.number }}
+          PR_BRANCH: ${{ github.head_ref }}
+        run: |
+          echo "{\"pr_number\": \"$PR_NUMBER\", \"pr_branch\": \"$PR_BRANCH\"}" > meta.json
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: meta.json
+          path: meta.json
diff --git a/.github/workflows/docs-preview-deploy.yml b/.github/workflows/docs-preview-deploy.yml
new file mode 100644
index 0000000000..b50367101f
--- /dev/null
+++ b/.github/workflows/docs-preview-deploy.yml
@@ -0,0 +1,67 @@
+name: Docs - preview deploy
+
+permissions:
+  contents: write
+  pull-requests: write
+
+on:
+  workflow_run:
+    workflows:
+      - "Docs - preview build"
+    types:
+      - completed
+
+# Since we use single-commit and force on the deploy action, only one deploy action can run at a time.
+concurrency:
+  group: preview_deploy
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: 'Download build artifact'
+        uses: actions/download-artifact@v4
+        with:
+          name: rendered-docs
+          path: rendered-docs
+          # TODO: what token is that?
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          run-id: ${{ github.event.workflow_run.id }}
+      - name: 'Download build meta'
+        uses: actions/download-artifact@v4
+        with:
+          name: meta.json
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          run-id: ${{ github.event.workflow_run.id }}
+
+      - name: Parse meta.json
+        run: |
+          echo "PR_NUMBER=$(jq -r .pr_number meta.json)" >> $GITHUB_ENV
+          echo "PR_BRANCH=$(jq -r .pr_branch meta.json)" >> $GITHUB_ENV
+
+      - name: Url slug variable
+        run: |
+          echo "URL_SLUG=${{ env.PR_NUMBER }}-${{ env.PR_BRANCH }}" >> $GITHUB_ENV
+
+      # TODO: this is where we have to use mike? but for now it's fine not to have it
+      - name: Deploy
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: rendered-docs
+          repository-name: neongreen/jj-pr-preview  # TODO: change
+          branch: 'main'
+          clean: true
+          target-folder: ${{ env.URL_SLUG }}
+          ssh-key: ${{ secrets.DEPLOY_KEY }}
+          commit-message: "Update preview for PR ${{ env.URL_SLUG }}"
+          single-commit: true
+
+      - name: Comment on the PR
+        uses: thollander/actions-comment-pull-request@v2
+        with:
+          message: |
+            Docs preview is available at https://neongreen.github.io/jj-pr-preview/${{ env.URL_SLUG }}.
+          pr_number: ${{ env.PR_NUMBER }}
+          comment_tag: 'docs-preview'