convert docs to Vitepress

.github/workflows/deploy_docs_5x.yml

@@ -22,3 +22,4 @@ jobs:
           git_remote_url: 'ssh://dokku@apps.cakephp.org:22/debugkit-docs-5'
           git_push_flags: '-f'
           ssh_private_key: ${{ secrets.DOKKU_SSH_PRIVATE_KEY }}
+          branch: '5.x'

.github/workflows/docs-validation.yml

@@ -0,0 +1,27 @@
+name: Documentation Validation
+
+on:
+    push:
+        branches:
+            - 5.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,26 +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
-
-# Prevent interactive timezone input
-ENV DEBIAN_FRONTEND=noninteractive
-RUN 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
-
-WORKDIR /code
-
-VOLUME ["/code"]
-
-CMD [ '/bin/bash' ]
+# ----------------------
+# 1. Build stage
+# ----------------------
+FROM node:22-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 (nginx)
+# ----------------------
+FROM nginx:1.27-alpine AS runner
+
+# Copy built files
+COPY --from=builder /app/docs/.vitepress/dist /usr/share/nginx/html
+
+# Expose port
+EXPOSE 80
+
+# Health check (optional)
+HEALTHCHECK CMD wget --quiet --tries=1 --spider http://localhost:80/ || exit 1
+
+# Start nginx
+CMD ["nginx", "-g", "daemon off;"]

docs/.gitignore

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

docs/.vitepress/config.js

@@ -0,0 +1,75 @@
+import baseConfig from '@cakephp/docs-skeleton/config'
+import { createRequire } from 'module'
+
+const require = createRequire(import.meta.url)
+const tocEn = require('./toc_en.json')
+const tocFr = require('./toc_fr.json')
+const tocJa = require('./toc_ja.json')
+const tocPt = require('./toc_pt.json')
+
+const versions = {
+  text: '5.x',
+  items: [
+    { text: '5.x (current)', link: 'https://book.cakephp.org/debugkit/5/', target: '_self' },
+    { text: '4.x', link: 'https://book.cakephp.org/debugkit/4/en/', target: '_self' },
+  ],
+}
+
+export default {
+  extends: baseConfig,
+  srcDir: '.',
+  title: 'DebugKit',
+  description: 'CakePHP DebugKit Documentation',
+  base: '/debugkit/5/',
+  rewrites: {
+    'en/:slug*': ':slug*',
+  },
+  sitemap: {
+    hostname: 'https://book.cakephp.org/debugkit/5/',
+  },
+  themeConfig: {
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/cakephp/debug_kit' },
+    ],
+    editLink: {
+      pattern: 'https://github.com/cakephp/debug_kit/edit/5.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/debugkit/' },
+      { ...versions },
+    ],
+  },
+  locales: {
+    root: {
+      label: 'English',
+      lang: 'en',
+      themeConfig: {
+        sidebar: tocEn,
+      },
+    },
+    fr: {
+      label: 'Français',
+      lang: 'fr',
+      themeConfig: {
+        sidebar: tocFr,
+      },
+    },
+    ja: {
+      label: '日本語',
+      lang: 'ja',
+      themeConfig: {
+        sidebar: tocJa,
+      },
+    },
+    pt: {
+      label: 'Português',
+      lang: 'pt',
+      themeConfig: {
+        sidebar: tocPt,
+      },
+    },
+  },
+}

docs/.vitepress/theme/index.js

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

docs/.vitepress/toc_en.json

@@ -0,0 +1,31 @@
+{
+  "/": [
+    {
+      "text": "Getting Started",
+      "collapsed": false,
+      "items": [
+        { "text": "Overview", "link": "/" },
+        { "text": "Configuration", "link": "/configuration" },
+        { "text": "Toolbar Usage", "link": "/toolbar" }
+      ]
+    },
+    {
+      "text": "Panels",
+      "collapsed": false,
+      "items": [
+        { "text": "History Panel", "link": "/history-panel" },
+        { "text": "Mail Panel", "link": "/mail-panel" },
+        { "text": "Custom Panels", "link": "/custom-panels" }
+      ]
+    },
+    {
+      "text": "Advanced",
+      "collapsed": false,
+      "items": [
+        { "text": "API Requests", "link": "/api-requests" },
+        { "text": "Helper Functions", "link": "/helper-functions" },
+        { "text": "API", "link": "https://api.cakephp.org/debugkit/" }
+      ]
+    }
+  ]
+}

docs/.vitepress/toc_fr.json

@@ -0,0 +1,12 @@
+{
+  "/fr/": [
+    {
+      "text": "CakePHP DebugKit",
+      "collapsed": false,
+      "items": [
+        { "text": "Aperçu", "link": "/fr/" },
+        { "text": "API", "link": "https://api.cakephp.org/debugkit/" }
+      ]
+    }
+  ]
+}

docs/.vitepress/toc_ja.json

@@ -0,0 +1,12 @@
+{
+  "/ja/": [
+    {
+      "text": "CakePHP DebugKit",
+      "collapsed": false,
+      "items": [
+        { "text": "概要", "link": "/ja/" },
+        { "text": "API", "link": "https://api.cakephp.org/debugkit/" }
+      ]
+    }
+  ]
+}

docs/.vitepress/toc_pt.json

@@ -0,0 +1,12 @@
+{
+  "/pt/": [
+    {
+      "text": "CakePHP DebugKit",
+      "collapsed": false,
+      "items": [
+        { "text": "Visão geral", "link": "/pt/" },
+        { "text": "API", "link": "https://api.cakephp.org/debugkit/" }
+      ]
+    }
+  ]
+}

docs/en/api-requests.md

@@ -0,0 +1,21 @@
+# API Requests
+
+If your application is API-only and does not render a frontend, you can still inspect DebugKit toolbar data directly.
+
+Open the toolbar endpoint with the request's DebugKit ID:
+
+```text
+http://localhost/debug-kit/toolbar/<debugkit-id>
+```
+
+The `<debugkit-id>` value is returned in the response headers:
+
+```text
+X-DEBUGKIT-ID: 5ef39604-ad5d-4ca4-85d8-8595e52373bb
+```
+
+For example:
+
+```text
+http://localhost/debug-kit/toolbar/5ef39604-ad5d-4ca4-85d8-8595e52373bb
+```