Merge pull request #326 from cakephp/3.x-vitepress

convert docs to Vitepress

Author: LordSimal

.github/workflows/deploy_docs_3x.yml

@@ -21,3 +21,4 @@ jobs:
         with:
           git_remote_url: 'ssh://dokku@apps.cakephp.org:22/authorization-docs-3'
           ssh_private_key: ${{ secrets.DOKKU_SSH_PRIVATE_KEY }}
+          branch: '3.x'

.github/workflows/docs-validation.yml

@@ -0,0 +1,27 @@
+name: Documentation Validation
+
+on:
+    push:
+        branches:
+            - 3.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.Dockerfile

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

docs/.gitignore

@@ -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 tocEs = require('./toc_es.json')
+const tocFr = require('./toc_fr.json')
+const tocJa = require('./toc_ja.json')
+
+const versions = {
+  text: '3.x',
+  items: [
+    { text: '3.x (current)', link: 'https://book.cakephp.org/authorization/3/', target: '_self' },
+    { text: '2.x', link: 'https://book.cakephp.org/authorization/2/en/', target: '_self' },
+  ],
+}
+
+export default {
+  extends: baseConfig,
+  srcDir: '.',
+  title: 'Authorization',
+  description: 'CakePHP Authorization Documentation',
+  base: '/authorization/3/',
+  rewrites: {
+    'en/:slug*': ':slug*',
+  },
+  sitemap: {
+    hostname: 'https://book.cakephp.org/authorization/3/',
+  },
+  themeConfig: {
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/cakephp/authorization' },
+    ],
+    editLink: {
+      pattern: 'https://github.com/cakephp/authorization/edit/3.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/authorization/' },
+      { ...versions },
+    ],
+  },
+  locales: {
+    root: {
+      label: 'English',
+      lang: 'en',
+      themeConfig: {
+        sidebar: tocEn,
+      },
+    },
+    es: {
+      label: 'Español',
+      lang: 'es',
+      themeConfig: {
+        sidebar: tocEs,
+      },
+    },
+    fr: {
+      label: 'Français',
+      lang: 'fr',
+      themeConfig: {
+        sidebar: tocFr,
+      },
+    },
+    ja: {
+      label: '日本語',
+      lang: 'ja',
+      themeConfig: {
+        sidebar: tocJa,
+      },
+    },
+  },
+}

docs/.vitepress/config.js

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

docs/.vitepress/theme/index.js

@@ -0,0 +1,25 @@
+{
+  "/": [
+    {
+      "text": "Getting Started",
+      "collapsed": false,
+      "items": [
+        { "text": "Quick Start", "link": "/" },
+        { "text": "Policies", "link": "/policies" },
+        { "text": "Policy Resolvers", "link": "/policy-resolvers" },
+        { "text": "Authorization Middleware", "link": "/middleware" },
+        { "text": "Checking Authorization", "link": "/checking-authorization" },
+        { "text": "AuthorizationComponent", "link": "/component" },
+        { "text": "Request Authorization Middleware", "link": "/request-authorization-middleware" }
+      ]
+    },
+    {
+      "text": "Migration Guides",
+      "collapsed": false,
+      "items": [
+        { "text": "2.0 Migration Guide", "link": "/2-0-migration-guide" },
+        { "text": "3.0 Migration Guide", "link": "/3-0-migration-guide" }
+      ]
+    }
+  ]
+}

docs/.vitepress/toc_en.json

@@ -0,0 +1,12 @@
+{
+  "/es/": [
+    {
+      "text": "Introducción",
+      "collapsed": false,
+      "items": [
+        { "text": "Inicio Rápido", "link": "/es/" },
+        { "text": "Policy", "link": "/es/policies" }
+      ]
+    }
+  ]
+}

docs/.vitepress/toc_es.json

@@ -0,0 +1,24 @@
+{
+  "/fr/": [
+    {
+      "text": "Prise en main",
+      "collapsed": false,
+      "items": [
+        { "text": "Introduction", "link": "/fr/" },
+        { "text": "Policies", "link": "/fr/policies" },
+        { "text": "Résolveurs de Policy", "link": "/fr/policy-resolvers" },
+        { "text": "Middleware Authorization", "link": "/fr/middleware" },
+        { "text": "Vérifier une Autorisation", "link": "/fr/checking-authorization" },
+        { "text": "AuthorizationComponent", "link": "/fr/component" },
+        { "text": "Middleware d'Autorisation de Requête", "link": "/fr/request-authorization-middleware" }
+      ]
+    },
+    {
+      "text": "Migration",
+      "collapsed": false,
+      "items": [
+        { "text": "Guide de Migration vers 2.0", "link": "/fr/2-0-migration-guide" }
+      ]
+    }
+  ]
+}