Skip to content

Commit 1ebeace

Browse files
dereuromarkdereuromark
authored
Migrate docs to VitePress (#323)
* Migrate docs to VitePress - Reorganize docs/ into guide/, behavior/, helper/, component/, model/, reference/ with kebab-case file names - Add VitePress config with unified sidebar, top nav, local search, sitemap, lastUpdated, brand-colored theme, and SVG logo - Add GitHub Pages deploy workflow building from docs/ on push to master - Move CONTRIBUTING.md back to repo root for GitHub auto-link - Add docs URL to composer.json support metadata - Update root README.md to point to https://dereuromark.github.io/cakephp-tools/ * Tweak hero, nav, sidebar collapse state, and logo - Drop misleading 4.x to 5.x shims claim from hero, features, sidebar, and meta description (the actual shims live in cakephp-shim) - Hero actions: replace Behaviors/Helpers buttons with Live Sandbox link - Top nav: drop Behaviors and Helpers (still in sidebar and features grid) - Sidebar: collapse all groups uniformly by default - Logo: redraw wrench head with proper bolt-cradle + slot opening; separate wrench-only favicon for small sizes * Reframe hero as user problems and add quick-start + ecosystem pages - Hero tagline + 6 feature cards rewritten from inventory-listing to problem-first framing - New guide/quick-start.md: 5-step concrete onboarding (install, base classes, trim+helpers, behavior, next steps) - New guide/ecosystem.md: map of Tools dependencies, frequently-paired plugins, and the wider author-plugin family - Sidebar Getting Started group includes both new entries
1 parent b4700d3 commit 1ebeace

62 files changed

Lines changed: 2970 additions & 158 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/deploy-docs.yml‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
paths:
8+
- 'docs/**'
9+
- '.github/workflows/deploy-docs.yml'
10+
workflow_dispatch:
11+
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
concurrency:
18+
group: pages
19+
cancel-in-progress: false
20+
21+
jobs:
22+
build:
23+
runs-on: ubuntu-latest
24+
steps:
25+
- name: Checkout
26+
uses: actions/checkout@v4
27+
with:
28+
fetch-depth: 0
29+
30+
- name: Setup Node
31+
uses: actions/setup-node@v4
32+
with:
33+
node-version: 20
34+
cache: npm
35+
cache-dependency-path: docs/package-lock.json
36+
37+
- name: Setup Pages
38+
uses: actions/configure-pages@v5
39+
40+
- name: Install dependencies
41+
run: npm ci
42+
working-directory: docs
43+
44+
- name: Build with VitePress
45+
run: npm run docs:build
46+
working-directory: docs
47+
48+
- name: Upload artifact
49+
uses: actions/upload-pages-artifact@v3
50+
with:
51+
path: docs/.vitepress/dist
52+
53+
deploy:
54+
environment:
55+
name: github-pages
56+
url: ${{ steps.deployment.outputs.page_url }}
57+
needs: build
58+
runs-on: ubuntu-latest
59+
steps:
60+
- name: Deploy to GitHub Pages
61+
id: deployment
62+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,7 @@ phpunit.xml
1111
/tests/test_files/node_modules/
1212
/tests/test_files/package-lock.json
1313
.phpcs.cache
14+
15+
/docs/node_modules/
16+
/docs/.vitepress/cache/
17+
/docs/.vitepress/dist/

docs/Contributing.md renamed to CONTRIBUTING.md

File renamed without changes.

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,4 +42,4 @@ This plugin for CakePHP 5 also contains some 4.x shims to ease migration of exis
4242

4343
## Installation & Docs
4444

45-
- [Documentation](docs/README.md)
45+
Full documentation: https://dereuromark.github.io/cakephp-tools/

‎composer.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,8 @@
2323
"homepage": "https://github.com/dereuromark/cakephp-tools",
2424
"support": {
2525
"issues": "https://github.com/dereuromark/cakephp-tools/issues",
26-
"source": "https://github.com/dereuromark/cakephp-tools"
26+
"source": "https://github.com/dereuromark/cakephp-tools",
27+
"docs": "https://dereuromark.github.io/cakephp-tools/"
2728
},
2829
"require": {
2930
"php": ">=8.2",

‎docs/.vitepress/config.ts‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
import { defineConfig } from 'vitepress'
2+
3+
function unifiedSidebar() {
4+
return [
5+
{
6+
text: 'Getting Started',
7+
items: [
8+
{ text: 'Overview', link: '/guide/' },
9+
{ text: '5-min Quick Start', link: '/guide/quick-start' },
10+
{ text: 'Installation', link: '/guide/install' },
11+
{ text: 'Upgrade Guide', link: '/guide/upgrade' },
12+
{ text: 'Shims', link: '/guide/shims' },
13+
{ text: 'Tools Backend', link: '/guide/backend' },
14+
{ text: 'Plugin Ecosystem', link: '/guide/ecosystem' },
15+
],
16+
},
17+
{
18+
text: 'Behaviors',
19+
collapsed: true,
20+
items: [
21+
{ text: 'Overview', link: '/behavior/' },
22+
{ text: 'AfterSave', link: '/behavior/after-save' },
23+
{ text: 'Bitmasked', link: '/behavior/bitmasked' },
24+
{ text: 'Encryption', link: '/behavior/encryption' },
25+
{ text: 'Jsonable', link: '/behavior/jsonable' },
26+
{ text: 'Passwordable', link: '/behavior/passwordable' },
27+
{ text: 'Reset', link: '/behavior/reset' },
28+
{ text: 'Slugged', link: '/behavior/slugged' },
29+
{ text: 'String', link: '/behavior/string' },
30+
{ text: 'Toggle', link: '/behavior/toggle' },
31+
{ text: 'Typographic', link: '/behavior/typographic' },
32+
],
33+
},
34+
{
35+
text: 'Helpers',
36+
collapsed: true,
37+
items: [
38+
{ text: 'Overview', link: '/helper/' },
39+
{ text: 'Common', link: '/helper/common' },
40+
{ text: 'Format', link: '/helper/format' },
41+
{ text: 'Form', link: '/helper/form' },
42+
{ text: 'Html', link: '/helper/html' },
43+
{ text: 'Icon', link: '/helper/icon' },
44+
{ text: 'Meter', link: '/helper/meter' },
45+
{ text: 'Progress', link: '/helper/progress' },
46+
{ text: 'Tree', link: '/helper/tree' },
47+
{ text: 'Typography', link: '/helper/typography' },
48+
],
49+
},
50+
{
51+
text: 'Components',
52+
collapsed: true,
53+
items: [
54+
{ text: 'Overview', link: '/component/' },
55+
{ text: 'Common', link: '/component/common' },
56+
{ text: 'Mobile', link: '/component/mobile' },
57+
{ text: 'RefererRedirect', link: '/component/referer-redirect' },
58+
],
59+
},
60+
{
61+
text: 'Model & Entity',
62+
collapsed: true,
63+
items: [
64+
{ text: 'Overview', link: '/model/' },
65+
{ text: 'Table', link: '/model/table' },
66+
{ text: 'Tokens', link: '/model/tokens' },
67+
{ text: 'Enum', link: '/model/enum' },
68+
{ text: 'StaticEnum', link: '/model/static-enum' },
69+
],
70+
},
71+
{
72+
text: 'Reference',
73+
collapsed: true,
74+
items: [
75+
{ text: 'Overview', link: '/reference/' },
76+
{ text: 'Login Links', link: '/reference/login-link' },
77+
{ text: 'Email', link: '/reference/email' },
78+
{ text: 'Controller', link: '/reference/controller' },
79+
{ text: 'Inflect Command', link: '/reference/inflect' },
80+
{ text: 'I18n', link: '/reference/i18n' },
81+
{ text: 'DateTime', link: '/reference/date-time' },
82+
{ text: 'URL', link: '/reference/url' },
83+
{ text: 'ExceptionTrap', link: '/reference/exception-trap' },
84+
{ text: 'FileLog', link: '/reference/file-log' },
85+
{ text: 'Datalist Widget', link: '/reference/datalist' },
86+
],
87+
},
88+
]
89+
}
90+
91+
export default defineConfig({
92+
title: 'cakephp-tools',
93+
description: 'The CakePHP Toolbox: behaviors, helpers, components, model and entity utilities for CakePHP applications.',
94+
base: '/cakephp-tools/',
95+
lastUpdated: true,
96+
sitemap: {
97+
hostname: 'https://dereuromark.github.io/cakephp-tools/',
98+
},
99+
head: [
100+
['link', { rel: 'icon', href: '/cakephp-tools/favicon.svg', type: 'image/svg+xml' }],
101+
],
102+
themeConfig: {
103+
logo: '/logo.svg',
104+
nav: [
105+
{ text: 'Guide', link: '/guide/', activeMatch: '/guide/' },
106+
{ text: 'Reference', link: '/reference/', activeMatch: '/(reference|behavior|helper|component|model)/' },
107+
{
108+
text: 'Links',
109+
items: [
110+
{ text: 'GitHub', link: 'https://github.com/dereuromark/cakephp-tools' },
111+
{ text: 'Packagist', link: 'https://packagist.org/packages/dereuromark/cakephp-tools' },
112+
{ text: 'Issues', link: 'https://github.com/dereuromark/cakephp-tools/issues' },
113+
],
114+
},
115+
],
116+
sidebar: {
117+
'/': unifiedSidebar(),
118+
},
119+
socialLinks: [
120+
{ icon: 'github', link: 'https://github.com/dereuromark/cakephp-tools' },
121+
],
122+
search: {
123+
provider: 'local',
124+
},
125+
editLink: {
126+
pattern: 'https://github.com/dereuromark/cakephp-tools/edit/master/docs/:path',
127+
text: 'Edit this page on GitHub',
128+
},
129+
footer: {
130+
message: 'Released under the MIT License.',
131+
copyright: 'Copyright Mark Scherer',
132+
},
133+
},
134+
})

‎docs/.vitepress/theme/custom.css‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
:root {
2+
--vp-c-brand-1: #c2410c;
3+
--vp-c-brand-2: #ea580c;
4+
--vp-c-brand-3: #fb923c;
5+
--vp-c-brand-soft: rgba(234, 88, 12, 0.14);
6+
7+
--vp-home-hero-name-color: transparent;
8+
--vp-home-hero-name-background: linear-gradient(135deg, #c2410c 0%, #b91c1c 100%);
9+
--vp-home-hero-image-background-image: linear-gradient(135deg, #c2410c 0%, #b91c1c 100%);
10+
--vp-home-hero-image-filter: blur(42px);
11+
}
12+
13+
.dark {
14+
--vp-c-brand-1: #fb923c;
15+
--vp-c-brand-2: #f97316;
16+
--vp-c-brand-3: #ea580c;
17+
}
18+
19+
.vp-doc table code,
20+
.vp-doc p code,
21+
.vp-doc li code {
22+
white-space: nowrap;
23+
}
24+
25+
.vp-doc .custom-block.tip {
26+
border-color: var(--vp-c-brand-1);
27+
}

‎docs/.vitepress/theme/index.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
import DefaultTheme from 'vitepress/theme'
2+
import './custom.css'
3+
4+
export default DefaultTheme

0 commit comments

Comments
 (0)