Introduction

Ava (Addy’s very adaptable) CMS is a fast, flexible, file-based PHP CMS for bespoke websites. Create a file, write in Markdown (with optional HTML), and you have a page. Edit it, refresh, and it’s live — no build step.

Your site stays transparent: content is plain text files you can read, move, and version. Use the optional admin dashboard when it’s convenient, or stick to your favourite editor and tools — Ava fits your workflow.

When you need more power, Ava adds it without hiding the structure: PHP themes, custom content types and fields, taxonomies, search, caching, plugins, and a friendly CLI. The idea stays simple: files in, website out.

Philosophy

Ava CMS is for people who like owning and understanding how their site works. It keeps the “just files” simplicity, while giving you dynamic tools when you need them.

Core Features

Files in, website out

Ava CMS projects are intentionally simple: your content is text files, your theme is a collection of HTML/PHP templates, and your configuration is plain PHP arrays. No magic, no hidden layers.

Here’s what a typical Ava CMS site looks like:

mysite/
├── app/                 # Your code
│   ├── config/          # Configuration files
│   │   ├── ava.php      # Main config (site, paths, caching)
│   │   ├── content_types.php
│   │   ├── taxonomies.php
│   │   └── users.php    # Admin users (managed by CLI)
│   ├── plugins/         # Enabled plugins
│   ├── snippets/        # Reusable PHP content blocks
│   └── themes/          # Your HTML/PHP templates
│       └── default/
│           ├── templates/
│           └── assets/
├── content/
│   ├── pages/           # Page content (hierarchical URLs)
│   ├── posts/           # Blog posts (/blog/{slug})
│   └── _taxonomies/     # Term registries
├── public/              # Web root
│   ├── media/           # Downloads referenced via /media/ alias
│   └── index.php        # Entry point
├── storage/cache/       # Content index and page cache (gitignored)
└── ava                  # CLI tool

How It Works

1. Write — Create Markdown files in your content/ folder using your own editor or the admin dashboard.
2. Index — Ava CMS scans your files and builds a fast index.
3. Render — Your theme turns that content into beautiful HTML.

Routing, sorting, pagination, and search are handled for you so you can focus on content and design.

Admin Dashboard

Ava CMS includes a fully featured admin dashboard designed for real content work. It’s optional — you can still edit files directly — but for teams or active sites it’s a major productivity boost.

The admin is especially strong with custom fields: complex schemas become clean, validated forms instead of manual YAML. You can create, edit, and organise content quickly without losing the transparency of file-based storage.

Key capabilities:

• Edit content — Create and edit Markdown with frontmatter generation
• Browse content — See what exists, its status, and where it lives on disk
• Manage taxonomies — Create and delete terms via a file-backed registry
• Upload media — Add images to your media folder
• Run diagnostics — Lint content, view logs, check system health
• Maintenance — Rebuild indexes and clear cached pages

See admin documentation →

Is Ava CMS for You?

Ava CMS is a great fit if:

• You want a site you can fully own, understand, and move between hosts.
• You like writing in a real editor instead of a web form.
• You know some HTML and CSS (or want to learn), and you’re happy to customise a theme.
• You want a fast site without build pipelines, deploy queues, or complicated tooling.
• You’d rather keep things simple: files first, database optional.

It won’t be a good fit if you need a drag-and-drop page builder or a huge marketplace of third‑party themes and plugins.

Performance

Ava CMS is designed to be fast by default, whether you have 100 posts or 100,000.

• Instant Publishing: No build step. Edit a file, refresh your browser, see it live.
• Smart Caching: A tiered caching system keeps page generation extremely fast.
• Scalable Backends: Start with the default Array backend for raw speed, or switch to SQLite for constant memory usage at scale.
• Static Speed: Enable full page caching to serve static HTML files, bypassing the application entirely for most visitors.

See full benchmarks and scaling guide →

Command Line Interface

Ava CMS includes a friendly CLI for managing your site. Run commands from your project root to check status, rebuild indexes, create content, and more.

./ava status

   ▄▄▄  ▄▄ ▄▄  ▄▄▄     ▄▄▄▄ ▄▄   ▄▄  ▄▄▄▄
  ██▀██ ██▄██ ██▀██   ██▀▀▀ ██▀▄▀██ ███▄▄
  ██▀██  ▀█▀  ██▀██   ▀████ ██   ██ ▄▄██▀

  ─── Site ──────────────────────────────────────────────

  Name:       My Site
  URL:        https://example.com

  ─── Content ───────────────────────────────────────────

  ◆ Page: 5 published
  ◆ Post: 38 published (4 drafts)

  ─── Page Cache ────────────────────────────────────────

  Status:     ● Enabled
  Cached:     42 pages

See full CLI reference →

Requirements

Ava CMS requires PHP 8.3 or later and SSH access for CLI commands. Most good hosts include this.

Required Extensions:

• mbstring — UTF-8 text handling
• json — Config and API responses
• ctype — String validation

These are bundled with most PHP installations.

Optional Extensions:

• pdo_sqlite — SQLite backend for large sites (10k+ items, constant memory)
• igbinary — Faster content indexing and smaller cache files
• opcache — Opcode caching for production

If igbinary isn't available, Ava CMS falls back to PHP's built-in serialize. Both work fine, igbinary is just faster.

Quick Start

Getting started with Ava CMS is simple and the default set-up can be put live in just a minute. Here are a few options:

Download and Upload

The simplest approach—no special tools required:

1. Download the latest release from GitHub Releases
2. Extract the ZIP file
3. Upload to your web host (via SFTP, your host's file manager, or however you prefer)
4. Run composer install to install dependencies
5. Configure your site by editing app/config/ava.php
6. Visit your site!

Download Latest Release (Command Line)

If you have SSH access and prefer the terminal, downloading the latest release is the cleanest approach (no Git required).

Option A: GitHub CLI (gh)

mkdir -p /tmp/ava-release && cd /tmp/ava-release
gh release download -R avacms/ava --pattern '*.zip' --clobber
unzip -q ./*.zip -d /path/to/your/site
cd /path/to/your/site
composer install

Option B: curl (uses PHP to pick the right ZIP asset)

REPO='avacms/ava'
URL="$(
  curl -fsSL "https://api.github.com/repos/$REPO/releases/latest" |
  php -r '$r=json_decode(stream_get_contents(STDIN), true);
    foreach (($r["assets"] ?? []) as $a) {
      if (str_ends_with($a["name"], ".zip")) { echo $a["browser_download_url"]; exit; }
    }
    fwrite(STDERR, "No .zip asset found on latest release\n");
    exit(1);'
)"

mkdir -p /tmp/ava-release && cd /tmp/ava-release
curl -fL "$URL" -o ava.zip
unzip -q ava.zip -d /path/to/your/site
cd /path/to/your/site
composer install

Then configure your site by editing app/config/ava.php and visit your site.

Local Development (Optional)

If you want to preview your site on your own computer before going live:

php -S localhost:8000 -t public

Then visit http://localhost:8000 in your browser.

Default Site

By default, Ava CMS comes with a simple example site. You can replace the content in the content/ folder and your theme in the app/themes/default/ folder to start building your site.

The default theme provides a clean, minimal starting point for your site. Customise it with your own styles, scripts and templates to match your vibe or build something entirely new.

Next Steps

• Configuration — Site settings, content types, and taxonomies
• Content — Writing pages and posts
• Hosting — Getting your site live
• Theming — Creating templates
• Admin — Optional dashboard
• CLI — Command-line tools
• Showcase — Community sites, themes, and plugins

Community

See what others are building with Ava CMS:

• Community Plugins — Extend Ava CMS with plugins shared by the community
• Community Themes — Ready-to-use themes for your site
• Sites Built with Ava CMS — Get inspired by what others have created

Contributing

Ava CMS is still fairly early and moving quickly, so I'm not looking for undiscussed pull requests or additional contributors just yet.

That said, I'd genuinely love your feedback:

• If you run into a bug, get stuck, or have a "this could be nicer" moment, please open an issue.
• Feature requests, ideas, and suggestions are very welcome.

If you prefer a more conversational place to ask questions and share ideas, join the Discord community.

License

Ava CMS is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should receive a copy of the GNU General Public License along with the program. If not, see https://www.gnu.org/licenses/.