Forage is a classic WordPress starter theme adapted from Vilare and informed by Roots Sage. The project background and implementation decisions are covered in more detail on my blog.
- Blade templating
- Vite asset compilation, bundling, and hot module replacement
- Biome CSS and JavaScript linting and formatting
- Modern CSS and JavaScript with no frontend runtime framework or preprocessor
- DocHooks for registering class methods with the WordPress hooks API
- CSS-driven generation of native WordPress
theme.jsonpresets - Built-in WordPress output cleanup and performance-oriented asset loading
- IndieWeb, Microformats2, and Schema.org support
Note
Forage is in active development and may introduce changes that require attention when updating.
If PHP OPcache is enabled, opcache.save_comments must also be enabled because Forage uses DocBlock annotations to register WordPress hooks.
themes/your-theme-name/
├── .vite/ # Vite plugins and build tests
├── app/ # Theme PHP
├── docs/ # Detailed project documentation
├── functions.php # WordPress theme bootstrap
├── inc/ # Bootstrap support
├── index.php # WordPress template fallback
├── resources/ # Assets and Blade views
├── screenshot.png # WordPress theme screenshot
├── style.css # WordPress theme metadata
├── template-custom.php # Example custom-template registration
├── theme.base.json # Hand-edited theme.json source
├── theme.json # Generated and tracked WordPress settings
└── vite.config.js # Vite configuration
Install Forage under wp-content/themes, then run these commands from the theme directory:
composer install
npm ci
npm run buildActivate Forage in WordPress after the initial build. The generated dist/manifest.json is required whenever the Vite development server is not running.
For local HMR detection, set the WordPress environment type and start Vite:
define('WP_ENVIRONMENT_TYPE', 'local');npm run devnpm run dev: start Vite with hot module replacementnpm run build: generatetheme.jsonand compile production assetsnpm run format: format CSS and JavaScript with Biome and PHP with PHPCBFnpm run lint: lint CSS and JavaScript with Biome and PHP with PHPCSnpm test: run build utility regression tests
Built assets in dist/ are generated and not committed. A production deployment must install dependencies and build the theme:
composer install --no-dev --optimize-autoloader
npm ci
npm run buildForage intentionally stops with an npm run build message when HMR is inactive and dist/manifest.json is missing.
- Development and asset workflow
- Editor styles, design tokens, and theme.json
- Prettify and Contact Form 7
- Upgrade notes and breaking changes
Forage includes Microformats2 and Schema.org markup intended to work with the WordPress IndieWeb ecosystem. Common companion plugins include:
- IndieWeb
- Webmention
- Syndication Links
- IndieAuth
- Post Kinds
- Micropub
IndieBlocks is another Gutenberg-oriented option that overlaps with several of these plugins.
The starter h-card displays a real author avatar when available and otherwise uses a local inline SVG instead of requesting Gravatar's generic image. Gravatar availability results are cached to avoid repeated server-side checks.
Comment avatars continue through WordPress's get_avatar() API so avatar and Webmention plugins can manage them.
When the IndieWeb plugin is active and a site has multiple users, select the appropriate Default Author under the IndieWeb settings. The h-card uses the current post author on singular content and the configured default elsewhere.
Forage keeps the classic WordPress template model and the parts of the Sage and Vilare architecture that remain useful without adopting their larger framework layers. It provides Blade templates, modern asset tooling, and selective WordPress editor integration while staying suitable as a relatively blank project starting point.
Contributions are welcome from everyone.
Forage is licensed under the GNU General Public License, version 3.