https://github.com/cakephp/docs-skeleton
A Vitepress skeleton tailored for CakePHP branded documentation projects
https://github.com/cakephp/docs-skeleton
Last synced: 29 days ago
JSON representation
A Vitepress skeleton tailored for CakePHP branded documentation projects
- Host: GitHub
- URL: https://github.com/cakephp/docs-skeleton
- Owner: cakephp
- License: mit
- Created: 2025-10-05T12:01:40.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-02-22T21:16:34.000Z (2 months ago)
- Last Synced: 2026-02-23T01:07:06.096Z (2 months ago)
- Language: JavaScript
- Size: 196 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# CakePHP Documentation Skeleton
A [VitePress](https://vitepress.dev/) based documentation skeleton for creating CakePHP branded documentation sites.
## Features
- 🎨 CakePHP branded theme and styling
- ⚙️ Easy configuration overrides
## Getting Started
### Installation
```bash
npm install
```
### Development
Start the development server:
```bash
npm run docs:dev
```
The documentation will be available at `http://localhost:5173`
### Building for Production
Build the static site:
```bash
npm run docs:build
```
Preview the production build:
```bash
npm run docs:preview
```
## Configuration
### Default Configuration
The default VitePress configuration is located in `.vitepress/config.js`. This file contains all the base settings for your documentation site.
For detailed information about VitePress configuration options, please refer to the [VitePress Configuration Reference](https://vitepress.dev/reference/site-config).
### Custom Overrides
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
**Example** (`config.js`):
```javascript
export default {
title: 'My Plugin Documentation',
themeConfig: {
sidebar: {
'/': [
{ text: 'Home', link: '/' },
{ text: 'Guide', link: '/guide' }
]
}
}
}
```
### Version Banner
You can display an e.g. "Outdated Version" banner on your documentation site by adding the following configuration:
```javascript
export default {
themeConfig: {
versionBanner: {
message: 'You are viewing an older version of this documentation.',
link: '/latest/',
linkText: 'Go to latest docs.'
}
}
}
```
## Writing Documentation
### Content Location
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`):
```javascript
export default {
substitutions: {
'|phpversion|': { value: '8.4', format: 'bold' },
'|minphpversion|': { value: '8.1', format: 'italic' },
'|myversion|': '1.0.0' // Simple string without formatting
}
}
```
**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
```
## Linting
Lint your configuration and scripts:
```bash
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)