convert docs to Vitepress (#184)

Author: LordSimal

.github/workflows/deploy_docs_2x.yml

@@ -20,4 +20,6 @@ jobs:
         uses: dokku/github-action@master
         with:
           git_remote_url: 'ssh://dokku@apps.cakephp.org:22/queue-docs-2'
+          git_push_flags: '-f'
           ssh_private_key: ${{ secrets.DOKKU_SSH_PRIVATE_KEY }}
+          branch: '2.x'

.github/workflows/docs-validation.yml

@@ -0,0 +1,27 @@
+name: Documentation Validation
+
+on:
+    push:
+        branches:
+            - 2.x
+        paths:
+            - 'docs/**'
+            - '.github/**'
+    pull_request:
+        paths:
+            - 'docs/**'
+            - '.github/**'
+
+jobs:
+    validate:
+        uses: cakephp/.github/.github/workflows/docs-validation.yml@5.x
+        with:
+            docs-path: 'docs'
+            vitepress-path: 'docs/.vitepress'
+            enable-config-js-check: true
+            enable-json-lint: true
+            enable-toc-check: true
+            enable-spell-check: true
+            enable-markdown-lint: true
+            enable-link-check: true
+            tools-ref: '5.x'

Dockerfile

@@ -1,25 +1,36 @@
-# Basic docker based environment
-# Necessary to trick dokku into building the documentation
-# using dockerfile instead of herokuish
-FROM ubuntu:22.04
-
-# Add basic tools
-RUN apt-get update && \
-  apt-get install -y build-essential \
-    software-properties-common \
-    curl \
-    git \
-    libxml2 \
-    libffi-dev \
-    libssl-dev && \
-  LC_ALL=C.UTF-8 add-apt-repository ppa:ondrej/php && \
-  apt-get update && \
-  apt-get install -y php8.1-cli php8.1-mbstring php8.1-xml php8.1-zip php8.1-intl php8.1-opcache php8.1-sqlite &&\
-  apt-get clean &&\
-  rm -rf /var/lib/apt/lists/*
-
-WORKDIR /code
-
-VOLUME ["/code"]
-
-CMD [ '/bin/bash' ]
+# ----------------------
+# 1. Build stage
+# ----------------------
+FROM node:24-alpine AS builder
+
+# Git is required because docs/package.json pulls a dependency from GitHub.
+RUN apk add --no-cache git openssh-client
+
+WORKDIR /app/docs
+
+# Copy dependency manifests first to preserve Docker layer caching.
+COPY docs/ ./
+RUN npm ci
+
+# Increase max-old-space-size to avoid memory issues during build
+#ENV NODE_OPTIONS="--max-old-space-size=8192"
+
+# Build the site.
+RUN npm run docs:build
+
+# ----------------------
+# 2. Runtime stage (angie)
+# ----------------------
+FROM docker.angie.software/angie:latest AS runner
+
+# Copy built files
+COPY --from=builder /app/docs/.vitepress/dist /usr/share/angie/html
+
+# Expose port
+EXPOSE 80
+
+# Health check (optional)
+HEALTHCHECK CMD wget --quiet --tries=1 --spider http://localhost:80/ || exit 1
+
+# Start angie
+CMD ["angie", "-g", "daemon off;"]

docs.Dockerfile

@@ -0,0 +1,4 @@
+node_modules
+*/public/
+.vitepress/cache
+.vitepress/dist

docs/.gitignore

@@ -0,0 +1,53 @@
+import baseConfig from '@cakephp/docs-skeleton/config'
+import { createRequire } from 'module'
+
+const require = createRequire(import.meta.url)
+const tocEn = require('./toc_en.json')
+
+const versions = {
+  text: '2.x',
+  items: [
+    { text: '2.x (current)', link: 'https://book.cakephp.org/queue/2/', target: '_self' },
+    { text: '1.x', link: 'https://book.cakephp.org/queue/1/en/', target: '_self' },
+  ],
+}
+
+export default {
+  extends: baseConfig,
+  srcDir: '.',
+  title: 'Queue',
+  description: 'CakePHP Queue Documentation',
+  base: '/queue/2/',
+  rewrites: {
+    'en/:slug*': ':slug*',
+  },
+  sitemap: {
+    hostname: 'https://book.cakephp.org/queue/2/',
+  },
+  themeConfig: {
+    siteTitle: false,
+    pluginName: 'Queue',
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/cakephp/queue' },
+    ],
+    editLink: {
+      pattern: 'https://github.com/cakephp/queue/edit/2.x/docs/:path',
+      text: 'Edit this page on GitHub',
+    },
+    sidebar: tocEn,
+    nav: [
+      { text: 'CakePHP', link: 'https://cakephp.org' },
+      { text: 'API', link: 'https://api.cakephp.org/queue/' },
+      { ...versions },
+    ],
+  },
+  locales: {
+    root: {
+      label: 'English',
+      lang: 'en',
+      themeConfig: {
+        sidebar: tocEn,
+      },
+    },
+  },
+}

docs/.vitepress/config.js

@@ -0,0 +1 @@
+export { default } from '@cakephp/docs-skeleton'

docs/.vitepress/theme/index.js

@@ -0,0 +1,29 @@
+{
+  "/": [
+    {
+      "text": "Getting Started",
+      "collapsed": false,
+      "items": [
+        { "text": "Installation and Configuration", "link": "/installation" },
+        { "text": "Defining and Queueing Jobs", "link": "/jobs" }
+      ]
+    },
+    {
+      "text": "Processing Work",
+      "collapsed": false,
+      "items": [
+        { "text": "Queueing Mail", "link": "/mail" },
+        { "text": "Custom Processors", "link": "/processors" },
+        { "text": "Running Workers", "link": "/workers" }
+      ]
+    },
+    {
+      "text": "Operations",
+      "collapsed": false,
+      "items": [
+        { "text": "Failed Jobs", "link": "/failed-jobs" },
+        { "text": "Worker Events", "link": "/events" }
+      ]
+    }
+  ]
+}