cakephp · josbeir · Mar 15, 2026 · Mar 15, 2026 · Mar 15, 2026
diff --git a/.vitepress/config.js b/.vitepress/config.js
@@ -1,94 +1,7 @@
-import { defineConfig } from 'vitepress'
-import { substitutionsReplacer } from './plugins/substitutions-replacer.js'
-import { deepMerge, loadConfigOverrides, applyBaseToHeadTags } from './utils.js'
+// This config is used for developing/previewing the skeleton itself.
+// Consumer projects use: import baseConfig from '@cakephp/docs-skeleton/config'
+import baseConfig from '../config/index.js'
 
-const defaultConfig = {
-  srcDir: 'docs',
-  title: 'CakePHP',
-  description: 'CakePHP Documentation - The rapid development PHP framework',
-  ignoreDeadLinks: true,
-  substitutions: {
-    '|phpversion|': { value: '8.4', format: 'bold' },
-    '|minphpversion|': { value: '8.1', format: 'italic' },
-    // Add more substitutions here as needed
-    // '|cakeversion|': { value: '5.1', format: 'bold' },
-    // '|projectname|': 'CakePHP',  // Simple string without formatting
-  },
-  head: [
-    ['link', { rel: 'icon', type: 'image/png', href: '/favicon/favicon-96x96.png', sizes: '96x96' }],
-    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/favicon/favicon.svg' }],
-    ['link', { rel: 'shortcut icon', href: '/favicon/favicon.ico' }],
-    ['link', { rel: 'apple-touch-icon', sizes: '180x180', href: '/favicon/apple-touch-icon.png' }],
-    ['meta', { name: 'apple-mobile-web-app-title', content: 'CakePHP' }],
-    ['link', { rel: 'manifest', href: '/favicon/site.webmanifest' }],
-    [
-      'script',
-      {
-        'data-collect-dnt': 'true',
-        async: 'true',
-        src: 'https://scripts.simpleanalyticscdn.com/latest.js'
-      }
-    ],
-    [
-      'script',
-      { async: '', src: 'https://www.googletagmanager.com/gtag/js?id=G-MD3J6G9QVX' }
-    ],
-    [
-      'script',
-      {},
-      `window.dataLayer = window.dataLayer || [];
-      function gtag(){dataLayer.push(arguments);}
-      gtag('js', new Date());
-      gtag('config', 'G-MD3J6G9QVX', { 'anonymize_ip': true });`
-    ]
-  ],
-  themeConfig: {
-    logo: '/logo.svg',
-    outline: {
-      level: [2, 3],
-    },
-    search: {
-      provider: 'local',
-    },
-    footer: {
-      message: 'Released under the MIT License.',
-      copyright: 'Copyright © Cake Software Foundation, Inc. All rights reserved.'
-    },
-    lastUpdated: {
-      text: 'Updated at',
-      formatOptions: {
-        dateStyle: 'full',
-        timeStyle: 'medium'
-      }
-    },
-    versionBanner: false
-  },
-  build: {
-    rollupOptions: {
-      output: {
-        manualChunks: {
-          'framework': ['vue']
-        }
-      }
-    }
-  },
-  markdown: {
-    lineNumbers: true,
-  },
-  locales: {}
+export default {
+  extends: baseConfig,
 }
-
-const overrides = await loadConfigOverrides(import.meta.url)
-const mergedConfig = deepMerge(defaultConfig, overrides)
-
-// Configure markdown plugins after mergedConfig is available
-mergedConfig.markdown.config = (md) => {
-  md.use(substitutionsReplacer, { substitutions: mergedConfig.substitutions || {} })
-}
-
-// Apply base path to head tags if base is specified
-if (overrides.base) {
-  applyBaseToHeadTags(mergedConfig, overrides.base)
-}
-
-export default defineConfig(mergedConfig)
diff --git a/.vitepress/theme/components/VersionBanner.vue b/.vitepress/theme/components/VersionBanner.vue
@@ -105,7 +105,11 @@ onUnmounted(() => {
     aria-live="polite"
   >
     {{ message }}
-    <a v-if="link" :href="link" target="_self">{{ linkText }}</a>
+    <a
+      v-if="link"
+      :href="link"
+      target="_self"
+    >{{ linkText }}</a>
   </div>
 </template>
 

diff --git a/README.md b/README.md
@@ -1,154 +1,158 @@
-# CakePHP Documentation Skeleton
+# CakePHP Documentation Theme
 
-A [VitePress](https://vitepress.dev/) based documentation skeleton for creating CakePHP branded documentation sites.
+A distributable [VitePress](https://vitepress.dev/) theme for CakePHP documentation sites. Install it as an npm dependency — it provides the CakePHP-branded theme, default config, and shared assets.
 
 ## Features
 
-- 🎨 CakePHP branded theme and styling
-- ⚙️ Easy configuration overrides
+- CakePHP branded theme extending VitePress default (custom fonts, colors, components)
+- Base config with sensible defaults (favicon, analytics, search, footer)
+- Text substitutions for version placeholders (`|phpversion|`, etc.)
+- Version banner component for outdated docs
+- Public asset syncing (favicon, fonts, icons, logo)
 
-## Getting Started
+## Using in a docs project
 
-### Installation
+### 1. Install
 
 ```bash
-npm install
+npm install @cakephp/docs-skeleton vitepress
 ```
 
-### Development
-
-Start the development server:
+### 2. Scaffold boilerplate
 
 ```bash
-npm run docs:dev
+npx cakedocs init
 ```
 
-The documentation will be available at `http://localhost:5173`
+This creates two files:
 
-### Building for Production
+| File | Purpose |
+|---|---|
+| `.vitepress/config.js` | Extends the skeleton's base config |
+| `.vitepress/theme/index.js` | Re-exports the CakePHP theme |
 
-Build the static site:
+### 3. Configure
 
-```bash
-npm run docs:build
-```
+Edit `.vitepress/config.js` — your overrides are merged with the base config via VitePress `extends`:
 
-Preview the production build:
+```javascript
+import baseConfig from '@cakephp/docs-skeleton/config'
 
-```bash
-npm run docs:preview
+export default {
+  extends: baseConfig,
+  base: '/5.x/',
+  themeConfig: {
+    sidebar: [],
+    nav: [],
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/cakephp/cakephp' },
+    ],
+  },
+  substitutions: {
+    '|phpversion|': { value: '8.4', format: 'bold' },
+    '|minphpversion|': { value: '8.1', format: 'italic' },
+  },
+}
 ```
 
-## Configuration
+### 4. Add scripts to `package.json`
+
+```json
+{
+  "scripts": {
+    "docs:dev":     "vitepress dev",
+    "docs:build":   "vitepress build",
+    "docs:preview": "vitepress preview"
+  }
+}
+```
 
-### Default Configuration
+### 5. Run
 
-The default VitePress configuration is located in `.vitepress/config.js`. This file contains all the base settings for your documentation site.
+```bash
+npm run docs:dev
+```
 
-For detailed information about VitePress configuration options, please refer to the [VitePress Configuration Reference](https://vitepress.dev/reference/site-config).
+### Project structure
 
-### Custom Overrides
+```
+your-project/
+├── .vitepress/
+│   ├── config.js              ← extends base config
+│   └── theme/
+│       └── index.js           ← re-exports theme
+├── docs/
+│   └── index.md
+└── package.json
+```
 
-To customize the configuration without modifying the core files:
+---
 
-1. Copy `config.default.js` to `config.js` in the project root
-2. Add your configuration overrides to the exported object
-3. Your overrides will be deep merged with the default configuration
+## Extending the theme
 
-**Example** (`config.js`):
+The theme re-export in `.vitepress/theme/index.js` can be customized:
 
 ```javascript
+import CakephpTheme from '@cakephp/docs-skeleton'
+import { h } from 'vue'
+import MyBanner from './components/MyBanner.vue'
+
 export default {
-  title: 'My Plugin Documentation',
-  themeConfig: {
-    sidebar: {
-      '/': [
-        { text: 'Home', link: '/' },
-        { text: 'Guide', link: '/guide' }
-      ]
-    }
+  extends: CakephpTheme,
+  Layout() {
+    return h(CakephpTheme.Layout, null, {
+      'layout-top': () => h(MyBanner),
+    })
   }
 }
 ```
 
-### Version Banner
+## Text Substitutions
 
-You can display an e.g. "Outdated Version" banner on your documentation site by adding the following configuration:
+Define placeholders replaced automatically in all Markdown:
 
 ```javascript
 export default {
-  themeConfig: {
-    versionBanner: {
-      message: 'You are viewing an older version of this documentation.',
-      link: '/latest/',
-      linkText: 'Go to latest docs.'
-    }
+  extends: baseConfig,
+  substitutions: {
+    '|phpversion|':    { value: '8.4', format: 'bold' },
+    '|minphpversion|': { value: '8.1', format: 'italic' },
+    '|cakeversion|':   '5.2',
   }
 }
 ```
 
-## Writing Documentation
-
-### Content Location
+In Markdown: `Requires PHP |phpversion| or higher.` renders as: Requires PHP **8.4** or higher.
 
-All markdown documentation files should be placed in the `docs/` directory.
-
-### Text Substitutions
-
-You can use placeholders in your markdown files that will be automatically replaced with configured values. This is useful for version numbers or other values that need to be updated across multiple files.
-
-**Configuration** (`config.js`):
+## Version Banner
 
 ```javascript
 export default {
-  substitutions: {
-    '|phpversion|': { value: '8.4', format: 'bold' },
-    '|minphpversion|': { value: '8.1', format: 'italic' },
-    '|myversion|': '1.0.0'  // Simple string without formatting
+  extends: baseConfig,
+  themeConfig: {
+    versionBanner: {
+      message: 'You are viewing docs for an older version.',
+      link: '/latest/',
+      linkText: 'Go to latest docs.'
+    }
   }
 }
 ```
 
-**Usage in Markdown**:
+---
 
-```markdown
-This plugin requires PHP |phpversion| or higher (minimum |minphpversion|).
-```
-
-**Result**: This plugin requires PHP **8.4** or higher (minimum *8.1*).
-
-## Project Structure
-
-```
-.
-├── .vitepress/           # VitePress configuration
-│   ├── config.js         # Main VitePress config (defaults)
-│   ├── utils.js          # Utility functions
-│   ├── theme/            # Custom theme components
-│   └── plugins/          # Markdown-it plugins
-├── docs/                 # Documentation content (markdown files)
-├── config.js             # Your configuration overrides (create from config.default.js)
-└── config.default.js     # Template for configuration overrides
-```
+## Skeleton development
 
-## Linting
-
-Lint your configuration and scripts:
+To work on the skeleton theme itself:
 
 ```bash
+npm install
+npm run docs:dev      # preview at http://localhost:5173
+npm run docs:build
 npm run lint
-```
-
-Auto-fix linting issues:
-
-```bash
 npm run lint:fix
 ```
 
 ## License
 
 Licensed under The MIT License. For full copyright and license information, please see the [LICENSE](LICENSE) file.
-
-## About CakePHP
-
-CakePHP is a rapid development framework for PHP which uses commonly known design patterns like Associative Data Mapping, Front Controller, and MVC. Learn more at [https://cakephp.org](https://cakephp.org)