A plugin for Ava CMS that generates a complete static HTML site from your content. Deploy to GitHub Pages, Netlify, Cloudflare Pages, S3, or any static hosting provider — no PHP required on the production server.
Alpha software. This plugin is under early development and testing. It could work for common site structures but will have edge cases with complex routing, custom plugin routes, or unusual configurations. Please report issues and test thoroughly before deploying to production.
- Generates all content pages, archive listings, and taxonomy pages
- Handles pagination automatically
- Generates sitemap.xml and feed.xml from Ava's bundled plugins
- Copies media files and theme assets
- Generates a JSON search index for client-side search
- Creates HTML redirect pages for
redirect_fromfrontmatter - Supports base URL override for subdirectory deployments
- Built-in preview server with clean URL support
- Respects
noindexfrontmatter — excluded from search index
- Ava CMS (latest version)
- PHP 8.3+
- Copy the
ssgfolder intoapp/plugins/:
app/plugins/ssg/
├── plugin.php
├── src/
│ ├── Builder.php
│ ├── PageRenderer.php
│ ├── RouteCollector.php
│ └── SearchIndexGenerator.php
└── README.md
- Enable the plugin in
app/config/ava.php:
'plugins' => [
'sitemap',
'feed',
'redirects',
'ssg',
],- Rebuild the content index:
./ava rebuild./ava static:buildThis generates the complete static site in the dist/ directory (default).
| Option | Description |
|---|---|
--clean | Remove output directory before building |
--output=DIR | Custom output directory (default: dist) |
--base-url=URL | Override the site's base URL for the build |
--no-assets | Skip copying static assets (media, theme files) |
--no-search | Skip generating the search index |
# Clean build
./ava static:build --clean
# Build to a custom directory
./ava static:build --output=public_html
# Build for a subdirectory deployment (e.g., GitHub Pages project site)
./ava static:build --base-url=https://user.github.io/my-project
# Build without search index
./ava static:build --no-search./ava static:serve
./ava static:serve --port=3000Starts a local PHP server pointing at the generated site with clean URL support. Visit http://127.0.0.1:8080 (default port).
./ava static:cleanRemoves the output directory entirely.
Add optional settings under 'ssg' in app/config/ava.php:
'ssg' => [
'output_dir' => 'dist', // Output directory (relative to project root)'base_url' => null, // Override site base URL (null = use site.base_url)'copy_media' => true, // Copy public/ directory contents'generate_search_index' => true, // Generate search-index.json'extra_paths' => [], // Additional URL paths to generate'exclude_paths' => [], // URL paths/patterns to skip'redirects' => 'html', // 'html' = generate redirect pages, 'none' = skip
],If you have custom routes registered in your theme or plugins that aren't automatically discovered, add them explicitly:
'extra_paths' => [
'/custom-page',
'/api/data.json',
],Skip specific paths or patterns from generation:
'exclude_paths' => [
'/api/*', // Wildcard suffix matching'/preview/*',
'/draft-page', // Exact match
],The generator creates clean URLs using path/index.html:
dist/
├── index.html ← / (homepage)
├── about/
│ └── index.html ← /about
├── blog/
│ ├── index.html ← /blog (archive)
│ └── hello-world/
│ └── index.html ← /blog/hello-world
├── category/
│ ├── index.html ← /category (taxonomy index)
│ └── tutorials/
│ └── index.html ← /category/tutorials
├── 404/
│ └── index.html ← Custom 404 page
├── feed.xml ← RSS feed
├── sitemap.xml ← Sitemap index
├── sitemap-post.xml ← Per-type sitemap
├── search-index.json ← Client-side search data
├── robots.txt ← From public/
├── media/ ← Copied from public/media/
│ └── ...
└── theme/ ← Theme CSS, JS, images
├── style.css
└── script.js
The plugin generates a search-index.json file containing all published, indexable content. Each entry includes:
{
"title": "Hello World",
"url": "/blog/hello-world",
"type": "post",
"excerpt": "Welcome to your new site...",
"body": "Plain text content stripped of Markdown...",
"date": "2024-01-15",
"category": ["tutorials"],
"tag": ["php", "beginner"]
}You can use this with client-side search libraries:
- Pagefind — Auto-indexes your HTML (recommended, ignores this file)
- Fuse.js — Lightweight fuzzy search
- Lunr.js — Full-text search in the browser
- Custom JavaScript — Fetch and filter
search-index.jsondirectly
./ava static:build --base-url=https://username.github.io/repo --clean
# Then push dist/ to gh-pages branchSet the build command (or build locally and drag-drop):
./ava rebuild && ./ava static:build --cleanPublish directory: dist
Upload the contents of dist/ to your web root. Ensure your server is configured to serve path/index.html for clean URLs, or configure it to try $uri/index.html as a fallback.
Nginx example:
server{root /var/www/html;indexindex.html;location / {try_files$uri$uri/index.html $uri/ =404;}error_page404 /404/index.html;}- All published content pages, archive listings, taxonomy pages
- Pagination for archives and taxonomy terms
- Plugin-generated routes (sitemap.xml, feed.xml)
- Theme assets and media files
- Redirects (as HTML meta-refresh pages)
- Custom 404 page
- Per-item CSS/JS assets
| Feature | Why | Workaround |
|---|---|---|
| Server-side search | Requires PHP at runtime | Use search-index.json with a client-side library |
| Preview mode | Needs PHP to check tokens | Preview locally with ./ava static:serve |
| Form handling | No server-side processing | Use a form service (Formspree, Netlify Forms, etc.) |
| Dynamic API routes | Custom PHP handlers | Pre-generate API responses as JSON files via extra_paths |
cache: false pages | All pages are static by definition | Content is still generated; it's just always "cached" |
| Webpage cache headers | Static hosts set their own headers | Configure caching at the hosting level |
| Comments / user content | No server-side state | Use a third-party service (Disqus, Giscus, etc.) |
- Develop locally using Ava normally (
php -S localhost:8000 -t public) - Preview and test your content with the dynamic site
- Generate the static site when ready to deploy:
./ava static:build --clean - Preview the static build with
./ava static:serve - Deploy the
dist/directory to your static host
This plugin is released under the GNU General Public License v3.0 (GPL-3.0), the same license as Ava CMS.