diff --git a/.github/workflows/publish_docs.yml b/.github/workflows/publish_docs.yml
new file mode 100644
index 00000000..f8cd75f5
--- /dev/null
+++ b/.github/workflows/publish_docs.yml
@@ -0,0 +1,55 @@
+name: Deploy Frappe Docker Docs to GitHub Pages
+
+on:
+  push:
+    branches: [docs]
+    paths:
+      - "docs/**"
+      - ".github/workflows/publish_docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm i --frozen-lockfile
+
+      - name: Build Docs site
+        run: pnpm docs:build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 316d9829..495139ae 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -5,8 +5,9 @@ import { withSidebar } from "vitepress-sidebar";
 const vitePressOptions = {
   title: "Frappe Docker Docs",
   description: "Frappe in a Container",
+  base: "/frappe_docker/",
   themeConfig: {
-    logo: "../images/frappe_docker.png",
+    logo: "/frappe-docker.png",
     // https://vitepress.dev/reference/default-theme-config
     nav: [{ text: "Home", link: "/" }],
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 72f9dee9..585b1f3f 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -89,7 +89,7 @@ Four predefined Dockerfiles are available, each serving different use cases:
 - **images/layered/** - Same final contents as `custom` but based on prebuilt images from Docker Hub; faster builds for production when using Frappe-managed dependency versions
 - **images/production/** - Installs only Frappe and ERPNext (not customizable with `apps.json`); best for **quick starts or exploration**; for real deployments, use `custom` or `layered`
 
-> **Note:** For detailed build arguments and advanced configuration options, see [docs/container-setup/01-overview.md](container-setup/01-overview.md).
+> **Note:** For detailed build arguments and advanced configuration options, see [docs/02-setup/01-overview.md](02-setup/01-overview.md).
 
 ### 📁 overrides/ - Compose File Extensions
 
@@ -859,11 +859,11 @@ Many teams use both: Frappe for back-office/admin tools, Django for customer-fac
 
 ### Key Files in This Repository
 
-- [`docs/development.md`](development.md) - Detailed development setup
-- [`docs/container-setup/env-variables.md`](container-setup/env-variables.md) - Environment variable reference
-- [`docs/single-server-example.md`](single-server-example.md) - Production deployment guide
-- [`docs/site-operations.md`](site-operations.md) - Common site management tasks
-- [`development/installer.py`](../development/installer.py) - Automated setup script
+- [`docs/05-development/01-development.md`](05-development/01-development.md) - Detailed development setup
+- [`docs/02-setup/04-env-variables.md`](02-setup/04-env-variables.md) - Environment variable reference
+- [`docs/02-setup/07-single-server-example.md`](02-setup/07-single-server-example.md) - Production deployment guide
+- [`docs/04-operations/01-site-operations.md`](04-operations/01-site-operations.md) - Common site management tasks
+- `development/installer.py` - Automated setup script
 - [`pwd.yml`](../pwd.yml) - Quick test configuration
 - [`compose.yaml`](../compose.yaml) - Base Docker Compose configuration
 
@@ -958,7 +958,7 @@ bench update                     # Update framework and apps
 
 ### Getting Help
 
-1. **Check existing docs** - Most issues covered in [`docs/troubleshoot.md`](troubleshoot.md)
+1. **Check existing docs** - Most issues covered in [`docs/07-troubleshooting/01-troubleshoot.md](07-troubleshooting/01-troubleshoot.md)
 2. **Search Frappe Forum** - [discuss.frappe.io](https://discuss.frappe.io)
 3. **GitHub Issues** - Search existing issues first
 4. **Discord/Telegram** - Community real-time chat (links in main repo)
@@ -969,7 +969,7 @@ Found issues or improvements for this guide?
 
 - Create an issue: [frappe_docker/issues](https://github.com/frappe/frappe_docker/issues)
 - Submit focused PRs: keep updates scoped and split large efforts across multiple pull requests.
-- Review [CONTRIBUTING.md](../CONTRIBUTING.md) for coding standards and review expectations.
+- Review CONTRIBUTING.md: for coding standards and review expectations.
 
 ---
 
diff --git a/docs/index.md b/docs/index.md
index 9c2f9096..3a108011 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -7,7 +7,7 @@ hero:
   # text: "Frappe in Container"
   tagline: "Documentation to use Docker based setup of Frappe framework"
   image:
-    src: ./images/frappe_docker.png
+    src: /frappe-docker.png
   actions:
     - theme: brand
       text: Getting Started
diff --git a/docs/images/frappe_docker.png b/docs/public/frappe-docker.png
similarity index 100%
rename from docs/images/frappe_docker.png
rename to docs/public/frappe-docker.png