dereuromark · dereuromark · May 4, 2026 · May 4, 2026
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
@@ -0,0 +1,62 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - 'docs/**'
+      - '.github/workflows/deploy-docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: docs
+
+      - name: Build with VitePress
+        run: npm run docs:build
+        working-directory: docs
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
@@ -8,3 +8,7 @@ composer.phar
 /.phpunit.result.cache
 /.phpunit.cache/
 .phpcs.cache
+
+/docs/node_modules/
+/docs/.vitepress/cache/
+/docs/.vitepress/dist/
diff --git a/docs/CONTRIBUTING.md → CONTRIBUTING.md b/docs/CONTRIBUTING.md → CONTRIBUTING.md
diff --git a/README.md b/README.md
@@ -47,7 +47,7 @@ While you can run multiple workers, and can (to some extent) spread these worker
 See [Sandbox app](https://sandbox.dereuromark.de/sandbox/queue-examples).
 
 ## Installation and Usage
-See [Documentation](docs/).
+Full documentation: https://dereuromark.github.io/cakephp-queue/
 
 ## Cronjob based background scheduling
 If you are looking for scheduling certain background jobs: This plugin works flawlessly with [QueueScheduler plugin](https://github.com/dereuromark/cakephp-queue-scheduler).
diff --git a/composer.json b/composer.json
@@ -28,7 +28,8 @@
 	],
 	"homepage": "https://github.com/dereuromark/cakephp-queue",
 	"support": {
-		"source": "https://github.com/dereuromark/cakephp-queue"
+		"source": "https://github.com/dereuromark/cakephp-queue",
+		"docs": "https://dereuromark.github.io/cakephp-queue/"
 	},
 	"require": {
 		"php": ">=8.2",

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -0,0 +1,107 @@
+import { defineConfig } from 'vitepress'
+
+function guideSidebar() {
+  return [
+    {
+      text: 'Guide',
+      items: [
+        { text: 'Overview', link: '/guide/' },
+        { text: 'Basic Setup', link: '/guide/basic-setup' },
+        { text: 'Queueing Jobs', link: '/guide/queueing-jobs' },
+        { text: 'Custom Tasks', link: '/guide/custom-tasks' },
+      ],
+    },
+    {
+      text: 'Operating',
+      items: [
+        { text: 'Configuration', link: '/guide/configuration' },
+        { text: 'Cron Setup', link: '/guide/cron' },
+        { text: 'Multi-Connection', link: '/guide/multi-connection' },
+        { text: 'Real-Time Progress', link: '/guide/realtime-progress' },
+      ],
+    },
+    {
+      text: 'Email',
+      items: [
+        { text: 'Mailing', link: '/guide/mailing' },
+      ],
+    },
+    {
+      text: 'Admin',
+      items: [
+        { text: 'Dashboard', link: '/admin/' },
+        { text: 'Statistics', link: '/admin/statistics' },
+      ],
+    },
+  ]
+}
+
+export default defineConfig({
+  title: 'cakephp-queue',
+  description: 'Reliable database-backed job queue for CakePHP with admin dashboard, retries, scheduling, and built-in tasks.',
+  base: '/cakephp-queue/',
+  lastUpdated: true,
+  sitemap: {
+    hostname: 'https://dereuromark.github.io/cakephp-queue/',
+  },
+  head: [
+    ['link', { rel: 'icon', href: '/cakephp-queue/favicon.svg', type: 'image/svg+xml' }],
+  ],
+  themeConfig: {
+    logo: '/logo.svg',
+    nav: [
+      { text: 'Guide', link: '/guide/', activeMatch: '/(guide|admin)/' },
+      { text: 'Tasks', link: '/tasks/', activeMatch: '/tasks/' },
+      { text: 'Reference', link: '/reference/', activeMatch: '/reference/' },
+      {
+        text: 'Links',
+        items: [
+          { text: 'GitHub', link: 'https://github.com/dereuromark/cakephp-queue' },
+          { text: 'Packagist', link: 'https://packagist.org/packages/dereuromark/cakephp-queue' },
+          { text: 'Issues', link: 'https://github.com/dereuromark/cakephp-queue/issues' },
+        ],
+      },
+    ],
+    sidebar: {
+      '/guide/': guideSidebar(),
+      '/admin/': guideSidebar(),
+      '/tasks/': [
+        {
+          text: 'Built-in Tasks',
+          items: [
+            { text: 'Overview', link: '/tasks/' },
+            { text: 'Execute', link: '/tasks/execute' },
+            { text: 'Email', link: '/tasks/email' },
+            { text: 'Mailer', link: '/tasks/mailer' },
+          ],
+        },
+      ],
+      '/reference/': [
+        {
+          text: 'Reference',
+          items: [
+            { text: 'Overview', link: '/reference/' },
+            { text: 'Tips', link: '/reference/tips' },
+            { text: 'Misc', link: '/reference/misc' },
+            { text: 'Limitations', link: '/reference/limitations' },
+            { text: 'Upgrading', link: '/reference/upgrading' },
+          ],
+        },
+      ],
+    },
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/dereuromark/cakephp-queue' },
+    ],
+    search: {
+      provider: 'local',
+    },
+    editLink: {
+      pattern: 'https://github.com/dereuromark/cakephp-queue/edit/master/docs/:path',
+      text: 'Edit this page on GitHub',
+    },
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright Mark Scherer',
+    },
+  },
+})
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
@@ -0,0 +1,27 @@
+:root {
+  --vp-c-brand-1: #0f766e;
+  --vp-c-brand-2: #14b8a6;
+  --vp-c-brand-3: #5eead4;
+  --vp-c-brand-soft: rgba(20, 184, 166, 0.14);
+
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: linear-gradient(135deg, #0f766e 0%, #0284c7 100%);
+  --vp-home-hero-image-background-image: linear-gradient(135deg, #0f766e 0%, #0284c7 100%);
+  --vp-home-hero-image-filter: blur(42px);
+}
+
+.dark {
+  --vp-c-brand-1: #5eead4;
+  --vp-c-brand-2: #2dd4bf;
+  --vp-c-brand-3: #14b8a6;
+}
+
+.vp-doc table code,
+.vp-doc p code,
+.vp-doc li code {
+  white-space: nowrap;
+}
+
+.vp-doc .custom-block.tip {
+  border-color: var(--vp-c-brand-1);
+}
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
@@ -0,0 +1,4 @@
+import DefaultTheme from 'vitepress/theme'
+import './custom.css'
+
+export default DefaultTheme
diff --git a/docs/README.md b/docs/README.md
diff --git a/docs/sections/admin_dashboard.md → docs/admin/index.md b/docs/sections/admin_dashboard.md → docs/admin/index.md
diff --git a/docs/sections/job_statistic.png → docs/admin/job_statistic.png b/docs/sections/job_statistic.png → docs/admin/job_statistic.png
diff --git a/docs/sections/statistics.md → docs/admin/statistics.md b/docs/sections/statistics.md → docs/admin/statistics.md
@@ -1,13 +1,13 @@
 # Statistics
 
 The plugin works completely without it, by just using the CLI shell commands.
-But if you want to browse the statistics via URL, you can enable the routing for it (see [Basic Setup](basic_setup.md)) and then access `/admin/queue`
+But if you want to browse the statistics via URL, you can enable the routing for it (see [Basic Setup](/guide/basic-setup)) and then access `/admin/queue`
 to see how status of your queue, statistics and settings.
 
 By default, the templates should work fine in both Foundation (v5+) and Bootstrap (v3+).
 Copy-and-paste to project level for any customization here.
 
 Here an example of historical job data for one specific "ProjectBranch" one:
-> ![job statistic](job_statistic.png)
+> ![job statistic](./job_statistic.png)
 
 It can be quite valuable to see the runtime (in seconds) over a progression of time.
diff --git a/docs/sections/bar_html.png → docs/guide/bar_html.png b/docs/sections/bar_html.png → docs/guide/bar_html.png
diff --git a/docs/sections/bar_text.png → docs/guide/bar_text.png b/docs/sections/bar_text.png → docs/guide/bar_text.png
diff --git a/docs/sections/basic_setup.md → docs/guide/basic-setup.md b/docs/sections/basic_setup.md → docs/guide/basic-setup.md
diff --git a/docs/sections/configuration.md → docs/guide/configuration.md b/docs/sections/configuration.md → docs/guide/configuration.md
@@ -167,7 +167,7 @@ You can set two main things on each task as property: timeout and retries.
     public ?int $retries = 1;
 ```
 Make sure you set the timeout high enough so that it could never run longer than this, otherwise you risk it being re-run while still being run.
-It is recommended setting it to at least 2x the maximum possible execution length. See [Concurrent workers](limitations.md)
+It is recommended setting it to at least 2x the maximum possible execution length. See [Concurrent workers](/reference/limitations)
 
 Set the retries to at least 1, otherwise it will never execute again after failure in the first run.
 

diff --git a/docs/sections/cron.md → docs/guide/cron.md b/docs/sections/cron.md → docs/guide/cron.md
diff --git a/docs/sections/custom_tasks.md → docs/guide/custom-tasks.md b/docs/sections/custom_tasks.md → docs/guide/custom-tasks.md
diff --git a/docs/guide/index.md b/docs/guide/index.md
@@ -0,0 +1,23 @@
+# Guide
+
+The Queue plugin runs background jobs out of your CakePHP database — no Redis, no RabbitMQ, no extra infrastructure. Jobs are persisted, retried on failure, and processed by one or more worker processes you trigger via cron, supervisor, or systemd.
+
+## Where to start
+
+- [Basic Setup](/guide/basic-setup) — install, load the plugin, run migrations.
+- [Queueing Jobs](/guide/queueing-jobs) — create jobs from your app code, with priorities, references, and progress tracking.
+- [Custom Tasks](/guide/custom-tasks) — write your own task classes.
+
+## Operating the queue
+
+- [Configuration](/guide/configuration) — runtime tuning (worker lifetime, timeouts, retries, multi-server).
+- [Cron Setup](/guide/cron) — start workers on a schedule.
+- [Multi-Connection](/guide/multi-connection) — run queues against multiple databases.
+- [Real-Time Progress](/guide/realtime-progress) — Mercure / SSE for live progress UIs.
+
+## Email handling
+
+- [Mailing](/guide/mailing) — queueing emails via QueueTransport, custom email tasks, and the built-in tasks reference.
+
+For built-in tasks (Execute, Email, Mailer), see [Tasks](/tasks/).
+For the admin UI, see [Admin Dashboard](/admin/).
diff --git a/docs/sections/mailing.md → docs/guide/mailing.md b/docs/sections/mailing.md → docs/guide/mailing.md
@@ -3,8 +3,8 @@
 There are multiple ways to send emails asynchronously using the Queue plugin:
 
 ## Using built-in tasks
-* [Email Task](./tasks/email.md) - For basic emails using Message class (most flexible)
-* [Mailer Task](./tasks/mailer.md) - For reusable templated emails using Mailer classes (best for standard emails)
+* [Email Task](/tasks/email) - For basic emails using Message class (most flexible)
+* [Mailer Task](/tasks/mailer) - For reusable templated emails using Mailer classes (best for standard emails)
 
 ## Using QueueTransport
 

diff --git a/docs/sections/multi_connection.md → docs/guide/multi-connection.md b/docs/sections/multi_connection.md → docs/guide/multi-connection.md
diff --git a/docs/sections/queueing_jobs.md → docs/guide/queueing-jobs.md b/docs/sections/queueing_jobs.md → docs/guide/queueing-jobs.md
@@ -78,7 +78,7 @@ TableRegistry::getTableLocator()->get('Queue.QueuedJobs')
     ]);
 ```
 
-It will use the plugin's `EmailTask` to send out emails via CLI. See the [Email task documentation](tasks/email.md) for more details.
+It will use the plugin's `EmailTask` to send out emails via CLI. See the [Email task documentation](/tasks/email) for more details.
 
 Important: Do not forget to set your [domain](https://book.cakephp.org/5/en/core-libraries/email.html#sending-emails-from-cli) when sending from CLI.
 
@@ -280,7 +280,7 @@ You can also use the more visual progress bar (or any custom one of yours):
 ```php
 echo $this->QueueProgress->progressBar($queuedJob, 18);
 ```
-![HTML5](bar_text.png)
+![HTML5](./bar_text.png)
 
 The length refers to the amount of chars to display.
 
@@ -291,7 +291,7 @@ $textProgressBar = $this->QueueProgress->progressBar($queuedJob, 18);
 echo $this->QueueProgress->htmlProgressBar($queuedJob, $textProgressBar);
 ```
 
-![HTML5](bar_html.png)
+![HTML5](./bar_html.png)
 
 The text one will only be visible for older browsers that do not support the HTML5 tag.
 

diff --git a/docs/sections/realtime_progress.md → docs/guide/realtime-progress.md b/docs/sections/realtime_progress.md → docs/guide/realtime-progress.md
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,44 @@
+---
+layout: home
+
+hero:
+  name: cakephp-queue
+  text: Background Queue for CakePHP
+  tagline: Reliable database-backed job queue with admin dashboard, retries, scheduling, multi-connection support, and built-in tasks for shell commands and email.
+  image:
+    src: /logo.svg
+    alt: cakephp-queue
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /guide/
+    - theme: alt
+      text: Built-in Tasks
+      link: /tasks/
+    - theme: alt
+      text: Admin Dashboard
+      link: /admin/
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/dereuromark/cakephp-queue
+
+features:
+  - icon: 💾
+    title: Database-Backed
+    details: No extra infrastructure — uses your existing database. Survives reboots, deploys, and worker crashes.
+  - icon: ⚙️
+    title: Admin Dashboard
+    details: Self-contained Bootstrap 5 admin UI for monitoring jobs, workers, and processes — with auth gate, multi-connection switcher, and stats.
+  - icon: 🔁
+    title: Retries and Scheduling
+    details: Configurable retries, priorities, notBefore scheduling, unique reference checks, and per-task timeout overrides.
+  - icon: 🧩
+    title: Built-in Tasks
+    details: Shipped Email, Mailer, and Execute tasks cover the common cases — drop in and queue.
+  - icon: 🌐
+    title: Multi-Connection
+    details: Run separate queues against multiple database connections, each with its own worker pool.
+  - icon: 📡
+    title: Real-Time Progress
+    details: Push live progress to the browser via Mercure / Server-Sent Events for long-running jobs.
+---