Configuration

Ava CMS's configuration is simple and transparent. All settings live in app/config/ as plain PHP files.

'site' => [
    'name'        => 'My Awesome Site',
    'base_url'    => 'https://example.com',    // Full URL, no trailing slash
    'og_image'    => '/media/social.jpg',      // Default social sharing image
    'timezone'    => 'Europe/London',          // php.net/timezones
    'locale'      => 'en_GB',                  // php.net/setlocale
    'date_format' => 'F j, Y',                 // php.net/datetime.format
],

Why PHP Configs?

We use PHP arrays instead of YAML or JSON because:

1. It's Readable: You can add comments to explain why you changed a setting.
2. It's Powerful: You can use constants, logic, or helper functions right in your config.
3. It's Standard: No special parsers or hidden .env files to debug.

The Config Files

Main Settings (ava.php)

This is where you set up your site's identity and behavior.

Site Identity

return [
    'site' => [
        'name'        => 'My Awesome Site',
        'base_url'    => 'https://example.com',    // Full URL, no trailing slash
        'og_image'    => '/media/social.jpg',      // Default social sharing image
        'timezone'    => 'Europe/London',          // php.net/timezones
        'locale'      => 'en_GB',                  // php.net/setlocale
        'date_format' => 'F j, Y',                 // php.net/datetime.format
        'title_format' => '{title} · {site}',      // null disables formatting
    ],
    // ...
];

In templates: Access site info via $site['name'], $site['url'], $site['timezone'], $site['locale'] (e.g. en_GB, for og:locale) and $site['lang'] (e.g. en-GB, for <html lang>). See Theming - Template Variables.

Paths

Directory locations for your content, themes, plugins, and other assets.

'paths' => [
    'content'  => 'content',       // Where your Markdown files live
    'themes'   => 'app/themes',    // Where theme folders live
    'plugins'  => 'app/plugins',   // Where plugin folders live
    'snippets' => 'app/snippets',  // Snippets for [snippet] shortcode
    'storage'  => 'storage',       // Cache, logs, and temporary files

    'aliases' => [
        '@media‎:' => '/media/',
    ],
],

All paths are relative to your project root unless they start with /.

Theme

'theme' => 'default',

See: Theming for theme structure, template variables, and development documentation.

Content Index

The content index is a binary snapshot of your content metadata—used to avoid parsing Markdown files on every request.

'content_index' => [
    'mode'               => 'auto',   // When to rebuild: auto, never, always
    'backend'            => 'array',  // Storage: array or sqlite
    'use_igbinary'       => true,     // Faster serialization if available
    'prerender_html'     => true,     // Pre-render Markdown during rebuild
    'background_rebuild' => false,    // auto mode: rebuild after the response is sent
],

See: Performance - Content Indexing for detailed explanations of modes, backends, tiered caching, and benchmarks.

Webpage Cache

The webpage cache stores fully-rendered HTML for near-instant serving. Only requests whose Host header matches site.base_url (or an entry in hosts) are cached.

'webpage_cache' => [
    'enabled' => true,
    'ttl'     => null,       // Seconds, or null = until rebuild
    'exclude' => [
        '/api/*',
        '/preview/*',
    ],
    'hosts'   => [],         // Extra hostnames allowed to use the cache
],

URLs with query strings other than ?paged=N and utm_* campaign parameters (for example search, filters and sorting) are never cached. To stop them overloading your server, rate limit them at the web server; see Hosting - Rate Limiting.

See: Performance - Webpage Caching for how it works, fast-path optimization, and cache management.

Generator Comment

'generator_comment' => false,

When enabled, Ava appends a comment to each page's HTML output. When the webpage cache is active, this is replaced with a cached variant and a <!-- Page cached: ... --> header comment is also added.

Set to true when you need these diagnostics. It defaults to false to minimize version information disclosed in production and keep HTML output clean.

Routing

'routing' => [
    'trailing_slash' => false,
],

See: Routing for URL styles, custom routes, and taxonomy URLs.

Content Parsing

Controls how Ava CMS processes your Markdown content files.

'content' => [
    'frontmatter' => [
        'format' => 'yaml',
    ],
    'markdown' => [
        'allow_html'       => true,
        'heading_ids'      => true,
        'disallowed_tags'  => ['script', 'noscript'],
    ],
    'id' => [
        'type' => 'ulid',
    ],
],

See: Writing Content for frontmatter fields and Markdown syntax.

Security

Ava includes security settings for shortcodes, preview tokens, and HTTP security headers.

'security' => [
    'shortcodes' => [
        'allow_php_snippets' => true,
    ],

    'headers' => [
        'content_security_policy' => [
            "default-src 'self'",
            "base-uri 'none'",
            "object-src 'none'",
            "frame-ancestors 'none'",
            "frame-src 'self' https://www.youtube.com https://www.youtube-nocookie.com https://player.vimeo.com",
            "form-action 'self'",
            "connect-src 'self' https:",        // External APIs, analytics
            "img-src 'self' data: https:",      // External images
            "font-src 'self' data: https:",     // Google Fonts, CDNs
            "style-src 'self' 'unsafe-inline' https:",
            "script-src 'self'",                // Add hosts here for analytics etc.
        ],
        'permissions_policy' => [
            'camera=()',
            'microphone=()',
            'geolocation=()',
            'payment=()',
            'usb=()',
            'interest-cohort=()',
        ],
    ],

    'preview_token' => null,
],

Preview token usage: Access drafts via https://example.com/path?preview=1&token=your-token

'headers' => [
    'content_security_policy' => [
        "default-src 'self'",
        "base-uri 'none'",
        "object-src 'none'",
        "frame-ancestors 'none'",
        "frame-src 'self' https://www.youtube.com",
        "form-action 'self'",
        "connect-src 'self' https://www.google-analytics.com",
        "img-src 'self' data:",
        "font-src 'self' data: https://fonts.gstatic.com",
        "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com",
        "script-src 'self' https://www.googletagmanager.com",
    ],
    // ... other headers
],

Allowing Analytics and Third-Party Scripts

The default script-src 'self' only runs script files served from your own site. To load a third-party script, add its host to script-src. For example, for Plausible:

"script-src 'self' https://plausible.io",

This also applies to external URLs in a page's assets.js frontmatter: add their host to script-src, or the browser will block them.

If a service gives you an inline snippet (a <script> block with code inside it), either move the code into a .js file in your theme and load it with $ava->asset(), or add 'unsafe-inline':

"script-src 'self' 'unsafe-inline' https://www.googletagmanager.com",

'unsafe-inline' lets any inline script run, including one injected by an attacker, so it weakens CSP's protection against XSS. Prefer an external file where you can.

Permissions Policy disables browser features you don't need. The defaults block camera, microphone, geolocation, payment APIs, USB access, and FLoC tracking. Remove items from the array if your site legitimately needs these features.

HSTS (Strict Transport Security) should be configured at your web server level (Apache, Nginx, Caddy), not in Ava's config.

See: Shortcodes - Snippets and Routing - Preview Mode.

Debug Mode

Control error visibility and logging for development and troubleshooting.

'debug' => [
    'enabled'        => false,
    'display_errors' => false,
    'log_errors'     => true,
    'level'          => 'errors',
],

Logs

Control log file size and automatic rotation.

'logs' => [
    'max_size'  => 10 * 1024 * 1024,   // 10 MB
    'max_files' => 3,
],

See: CLI - Logs for log viewing and management commands.

CLI Appearance

'cli' => [
    'theme' => 'cyan',
],

Plugins

'plugins' => [
    'sitemap',
    'feed',
    'redirects',
],

Array of plugin folder names to activate. Plugins load in the order listed.

See: Bundled Plugins for sitemap, RSS feed, and redirects configuration.

Custom Settings

Add your own site-specific configuration. Access values in templates with $ava->config():

// In ava.php
'analytics' => [
    'tracking_id' => 'G-XXXXXXXXXX',
    'enabled'     => true,
],

// In templates
<?php if ($ava->config('analytics.enabled')): ?>
    <!-- Analytics code for <?= $ava->config('analytics.tracking_id') ?> -->
<?php endif; ?>

Content Types: content_types.php

Define what kinds of content your site has. Each content type specifies where files live, how URLs are generated, and which templates to use.

<?php

return [
    'page' => [
        'label'       => 'Pages',
        'icon'        => 'description',
        'content_dir' => 'pages',
        'url' => [
            'type' => 'hierarchical',
            'base' => '/',
        ],
        'templates' => [
            'single' => 'page.php',
        ],
        'taxonomies' => [],
        'sorting'    => 'manual',
        'search' => [
            'enabled' => true,
            'fields'  => ['title', 'body'],
        ],
    ],

    'post' => [
        'label'       => 'Posts',
        'icon'        => 'article',
        'content_dir' => 'posts',
        'url' => [
            'type'    => 'pattern',
            'pattern' => '/blog/{slug}',
            'archive' => '/blog',
        ],
        'templates' => [
            'single'  => 'post.php',
            'archive' => 'archive.php',
        ],
        'taxonomies' => ['category', 'tag'],
        'sorting'    => 'date_desc',
        'search' => [
            'enabled' => true,
            'fields'  => ['title', 'excerpt', 'body'],
        ],
    ],
];

Content Type Options

Taxonomies: taxonomies.php

Taxonomies organize content into groups (categories, tags, authors, etc.).

<?php

return [
    'category' => [
        'label'        => 'Categories',
        'icon'         => 'folder',
        'hierarchical' => true,
        'public'       => true,

        'rewrite' => [
            'base'      => '/category',
            'separator' => '/',
        ],

        'behaviour' => [
            'allow_unknown_terms' => true,
            'hierarchy_rollup'    => true,
        ],

        'ui' => [
            'show_counts' => true,
            'sort_terms'  => 'name_asc',
        ],
    ],

    'tag' => [
        'label'        => 'Tags',
        'icon'         => 'tag',
        'hierarchical' => false,
        'public'       => true,

        'rewrite' => [
            'base' => '/tag',
        ],

        'behaviour' => [
            'allow_unknown_terms' => true,
        ],

        'ui' => [
            'show_counts' => true,
            'sort_terms'  => 'count_desc',
        ],
    ],
];

Taxonomy Options

See: Taxonomies for assigning terms to content, term storage, hierarchical terms, and template helpers.

Environment-Specific Config

Use PHP logic to override settings per environment:

// app/config/ava.php

$config = [
    'site' => [
        'name'     => 'My Site',
        'base_url' => 'https://example.com',
    ],
    'content_index' => ['mode' => 'never'],
    'debug' => ['enabled' => false],
];

// Development overrides
if (getenv('APP_ENV') === 'development') {
    $config['site']['base_url'] = 'http://localhost:8000';
    $config['content_index']['mode'] = 'auto';
    $config['debug'] = [
        'enabled'        => true,
        'display_errors' => true,
        'level'          => 'all',
    ];
}

return $config;

Set the environment variable in your server config:

export APP_ENV=development