From 989a4e662bb8d388f73a6ec731985b7bbaea8942 Mon Sep 17 00:00:00 2001
From: Xingyao Wang <xingyao@all-hands.dev>
Date: Sat, 6 Sep 2025 10:10:21 -0400
Subject: [PATCH] feat: integrate with unified docs repository (#10830)

Co-authored-by: openhands <openhands@all-hands.dev>
---
 .github/workflows/dispatch-to-docs.yml | 23 +++++++++++++++
 docs/README.md                         | 41 +++++++++++++++++++-------
 2 files changed, 53 insertions(+), 11 deletions(-)
 create mode 100644 .github/workflows/dispatch-to-docs.yml

diff --git a/.github/workflows/dispatch-to-docs.yml b/.github/workflows/dispatch-to-docs.yml
new file mode 100644
index 0000000000..b784f67392
--- /dev/null
+++ b/.github/workflows/dispatch-to-docs.yml
@@ -0,0 +1,23 @@
+name: Dispatch to docs repo
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+  workflow_dispatch:
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        repo: ["All-Hands-AI/docs"]
+    steps:
+      - name: Push to docs repo
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.ALLHANDS_BOT_GITHUB_PAT }}
+          repository: ${{ matrix.repo }}
+          event-type: update
+          client-payload: '{"ref": "${{ github.ref }}", "sha": "${{ github.sha }}", "module": "openhands", "branch": "main"}'
diff --git a/docs/README.md b/docs/README.md
index 1c505ed617..299ae6938e 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,17 +1,36 @@
-# Setup
+# OpenHands Documentation
 
-```
+This directory contains the documentation for OpenHands. The documentation is automatically synchronized with the [All-Hands-AI/docs](https://github.com/All-Hands-AI/docs) repository, which hosts the unified documentation site using Mintlify.
+
+## Documentation Structure
+
+The documentation files in this directory are automatically included in the main documentation site via Git submodules. When you make changes to documentation in this repository, they will be automatically synchronized to the docs repository.
+
+## How It Works
+
+1. **Automatic Sync**: When documentation changes are pushed to the `main` branch, a GitHub Action automatically notifies the docs repository
+2. **Submodule Update**: The docs repository updates its submodule reference to include your latest changes  
+3. **Site Rebuild**: Mintlify automatically rebuilds and deploys the documentation site
+
+## Making Documentation Changes
+
+Simply edit the documentation files in this directory as usual. The synchronization happens automatically when changes are merged to the main branch.
+
+## Local Development
+
+For local documentation development in this repository only:
+
+```bash
 npm install -g mint
-```
-
-or
-
-```
+# or
 yarn global add mint
-```
 
-# Preview
-
-```
+# Preview local changes
 mint dev
 ```
+
+For the complete unified documentation site, work with the [All-Hands-AI/docs](https://github.com/All-Hands-AI/docs) repository.
+
+## Configuration
+
+The Mintlify configuration (`docs.json`) has been moved to the root of the [All-Hands-AI/docs](https://github.com/All-Hands-AI/docs) repository to enable unified documentation across multiple repositories.