convert docs to Vitepress

.github/workflows/deploy_docs_5x.yml

@@ -12,13 +12,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Cloning repo
-        uses: actions/checkout@v2
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Push to dokku
         uses: dokku/github-action@master
         with:
           git_remote_url: 'ssh://dokku@apps.cakephp.org:22/elasticsearch-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

@@ -0,0 +1,36 @@
+# ----------------------
+# 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/.gitignore

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

docs/.vitepress/config.js

@@ -0,0 +1,64 @@
+import baseConfig from '@cakephp/docs-skeleton/config'
+import { createRequire } from 'module'
+
+const require = createRequire(import.meta.url)
+const tocEn = require('./toc_en.json')
+const tocJa = require('./toc_ja.json')
+
+const versions = {
+  text: '5.x',
+  items: [
+    { text: '5.x (current)', link: 'https://book.cakephp.org/elasticsearch/5/', target: '_self' },
+    { text: '4.x', link: 'https://book.cakephp.org/elasticsearch/4/', target: '_self' },
+    { text: '3.x', link: 'https://book.cakephp.org/elasticsearch/3/', target: '_self' },
+  ],
+}
+
+export default {
+  extends: baseConfig,
+  srcDir: '.',
+  title: 'ElasticSearch',
+  description: 'CakePHP ElasticSearch Documentation',
+  base: '/elasticsearch/5/',
+  rewrites: {
+    'en/:slug*': ':slug*',
+    'ja/:slug*': 'ja/:slug*',
+  },
+  sitemap: {
+    hostname: 'https://book.cakephp.org/elasticsearch/5/',
+  },
+  themeConfig: {
+    siteTitle: false,
+    pluginName: 'ElasticSearch',
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/cakephp/elastic-search' },
+    ],
+    editLink: {
+      pattern: 'https://github.com/cakephp/elastic-search/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/elasticsearch/' },
+      { ...versions },
+    ],
+  },
+  locales: {
+    root: {
+      label: 'English',
+      lang: 'en',
+      themeConfig: {
+        sidebar: tocEn,
+      },
+    },
+    ja: {
+      label: 'Japanese',
+      lang: 'ja',
+      link: '/ja/',
+      themeConfig: {
+        sidebar: tocJa,
+      },
+    },
+  },
+}

docs/.vitepress/theme/index.js

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

docs/.vitepress/toc_en.json

@@ -0,0 +1,30 @@
+{
+  "/": [
+    {
+      "text": "Getting Started",
+      "collapsed": false,
+      "items": [
+        { "text": "Installation and Configuration", "link": "/installation" },
+        { "text": "Indexes and Documents", "link": "/indexes-and-documents" },
+        { "text": "Searching and Saving", "link": "/searching-and-saving" }
+      ]
+    },
+    {
+      "text": "Advanced Topics",
+      "collapsed": false,
+      "items": [
+        { "text": "Embedded Documents", "link": "/embedded-documents" },
+        { "text": "Testing", "link": "/testing" }
+      ]
+    },
+    {
+      "text": "Migration",
+      "collapsed": false,
+      "items": [
+        { "text": "5.0 Upgrade Guide", "link": "/5-0-upgrade-guide" },
+        { "text": "4.0 Upgrade Guide", "link": "/4-0-upgrade-guide" },
+        { "text": "3.0 Upgrade Guide", "link": "/3-0-upgrade-guide" }
+      ]
+    }
+  ]
+}

docs/.vitepress/toc_ja.json

@@ -0,0 +1,11 @@
+{
+  "/ja/": [
+    {
+      "text": "ドキュメント",
+      "collapsed": false,
+      "items": [
+        { "text": "ElasticSearch", "link": "/ja/" }
+      ]
+    }
+  ]
+}

docs/en/3-0-upgrade-guide.md

@@ -0,0 +1,22 @@
+# 3.0 Upgrade Guide
+
+If you are upgrading from an earlier version of this plugin, this page collects the application changes you may need to make.
+
+## Types Renamed to Indexes
+
+Because of Elasticsearch 5 and 6 changes, the plugin no longer supports multiple types in the same index. All of your type classes therefore need to be renamed to indexes.
+
+For example:
+
+- `App\Model\Type\ArticlesType` becomes `App\Model\Index\ArticlesIndex`
+- `Type` base classes become `Index` base classes
+
+Index classes assume that the mapping type uses the singularized index name. For example, the `articles` index uses the `article` mapping type.
+
+## Breaking Changes
+
+- `Index::entityClass()` was removed. Use `getEntityClass()` or `setEntityClass()` instead.
+- `ResultSet::hasFacets()` was removed because Elastica no longer exposes this method.
+- `ResultSet::getFacets()` was removed because Elastica no longer exposes this method.
+- `Type` is now `Index`.
+- `TypeRegistry` is now `IndexRegistry`.

docs/en/4-0-upgrade-guide.md

@@ -0,0 +1,31 @@
+# 4.0 Upgrade Guide
+
+::: warning Requirements
+CakePHP ElasticSearch `4.x` requires CakePHP `5.x`.
+:::
+
+## Breaking Changes
+
+- Native PHP types were added where possible. This improves type safety but may expose incompatibilities in application code.
+- `Query` no longer uses `Cake\ORM\QueryTrait`, which removed several inherited methods that were never used by this plugin.
+- `Query::isEagerLoaded()` and `Query::eagerLoaded()` were removed.
+
+## Indexes
+
+`IndexRegistry` was deprecated in `4.x`.
+
+Old code:
+
+```php
+use Cake\ElasticSearch\IndexRegistry;
+
+$articles = IndexRegistry::get('Articles');
+```
+
+New code:
+
+```php
+use Cake\Datasource\FactoryLocator;
+
+$articles = FactoryLocator::get('ElasticSearch')->get('Articles');
+```