diff --git a/.forgejo/workflows/docs.yml b/.forgejo/workflows/docs.yml
new file mode 100644
index 0000000..2cc8cba
--- /dev/null
+++ b/.forgejo/workflows/docs.yml
@@ -0,0 +1,57 @@
+name: Publish Docs
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - ".forgejo/workflows/docs.yml"
+      - "README.md"
+      - "make_docs.sh"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "docs/**"
+      - "meanas/**"
+  workflow_dispatch:
+
+jobs:
+  publish-docs:
+    runs-on: docker
+    container:
+      image: python:3.13-bookworm
+    env:
+      DOCS_SITE_URL: ${{ vars.DOCS_SITE_URL }}
+    steps:
+      - name: Check out the repository
+        uses: https://data.forgejo.org/actions/checkout@v4
+
+      - name: Install build dependencies
+        run: |
+          apt-get update
+          apt-get install -y --no-install-recommends git
+
+      - name: Install docs dependencies
+        run: |
+          pip install -e '.[docs]'
+
+      - name: Build documentation
+        run: |
+          ./make_docs.sh
+
+      - name: Publish docs branch
+        run: |
+          ./scripts/publish_docs_branch.sh site docs-site
+
+      - name: Write job summary
+        run: |
+          {
+            echo "## Published docs"
+            echo
+            echo "- Branch: \`docs-site\`"
+            if [[ -n "${DOCS_SITE_URL:-}" ]]; then
+              echo "- URL: ${DOCS_SITE_URL}"
+            else
+              echo "- URL: set the \`DOCS_SITE_URL\` repository variable to advertise the published site"
+            fi
+            echo "- Recommended repository setting: configure the Wiki tab to point at the published docs URL"
+          } >> "$GITHUB_STEP_SUMMARY"
diff --git a/README.md b/README.md
index 01bc257..b0e1619 100644
--- a/README.md
+++ b/README.md
@@ -120,6 +120,16 @@ API and workflow docs are generated from the package docstrings with
 [MkDocs](https://www.mkdocs.org/), [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/),
 and [mkdocstrings](https://mkdocstrings.github.io/).
 
+When hosted on a Forgejo instance, the intended setup is:
+
+- publish the generated site from a dedicated `docs-site` branch
+- serve that branch from the instance's static-pages host
+- point the repository's **Wiki** tab at the published docs URL
+
+The repository contains a Forgejo Actions workflow for publishing the docs
+branch automatically. Set the repository variable `DOCS_SITE_URL` to the final
+published URL so MkDocs can generate canonical links correctly.
+
 Install the docs toolchain with:
 
 ```bash
@@ -138,6 +148,9 @@ This produces:
 - a combined printable single-page HTML site under `site/print_page/`
 - an optional fully inlined `site/standalone.html` when `htmlark` is available
 
+The same build output is what the Forgejo Actions workflow publishes to the
+`docs-site` branch.
+
 The docs build uses a local MathJax bundle vendored under `docs/assets/`, so
 the rendered HTML does not rely on external services for equation rendering.
 
diff --git a/mkdocs.yml b/mkdocs.yml
index a6ab1de..837284c 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,6 +1,6 @@
 site_name: meanas
 site_description: Electromagnetic simulation tools
-site_url: ""
+site_url: !ENV [DOCS_SITE_URL, ""]
 repo_url: https://mpxd.net/code/jan/meanas
 repo_name: meanas
 docs_dir: docs
diff --git a/scripts/publish_docs_branch.sh b/scripts/publish_docs_branch.sh
new file mode 100755
index 0000000..0fe1c4e
--- /dev/null
+++ b/scripts/publish_docs_branch.sh
@@ -0,0 +1,52 @@
+#!/bin/bash
+
+set -Eeuo pipefail
+
+if [[ $# -ne 2 ]]; then
+    echo "usage: $0 <site-dir> <branch>" >&2
+    exit 2
+fi
+
+SITE_DIR="$1"
+BRANCH="$2"
+
+if [[ ! -d "$SITE_DIR" ]]; then
+    echo "site directory not found: $SITE_DIR" >&2
+    exit 1
+fi
+
+if ! git rev-parse --git-dir >/dev/null 2>&1; then
+    echo "must be run inside a git repository" >&2
+    exit 1
+fi
+
+TMP_DIR="$(mktemp -d)"
+cleanup() {
+    git worktree remove --force "$TMP_DIR" >/dev/null 2>&1 || true
+}
+trap cleanup EXIT
+
+git fetch origin "$BRANCH" || true
+
+if git show-ref --verify --quiet "refs/remotes/origin/$BRANCH"; then
+    git worktree add --detach "$TMP_DIR" "origin/$BRANCH"
+else
+    git worktree add --detach "$TMP_DIR"
+    git -C "$TMP_DIR" checkout --orphan "$BRANCH"
+fi
+
+find "$TMP_DIR" -mindepth 1 -maxdepth 1 ! -name '.git' -exec rm -rf {} +
+cp -R "$SITE_DIR"/. "$TMP_DIR"/
+touch "$TMP_DIR/.nojekyll"
+
+git -C "$TMP_DIR" config user.name "${GIT_AUTHOR_NAME:-Forgejo Actions}"
+git -C "$TMP_DIR" config user.email "${GIT_AUTHOR_EMAIL:-forgejo-actions@localhost}"
+git -C "$TMP_DIR" add -A
+
+if git -C "$TMP_DIR" diff --cached --quiet; then
+    echo "no docs changes to publish"
+    exit 0
+fi
+
+git -C "$TMP_DIR" commit -m "Publish docs for ${GITHUB_SHA:-local build}"
+git -C "$TMP_DIR" push --force origin "HEAD:${BRANCH}"