Page Indexing

VelvetCMS Core keeps page content on disk, but it does not rely on full file scans for every list query. Instead, it builds a page index from frontmatter and file metadata.

What gets indexed #

The index stores the fields Core needs for fast lookups and sorting:

• slug
• source path
• file modification time
• format
• title
• status
• layout
• excerpt
• trusted flag
• created, updated, and published timestamps
• custom frontmatter fields

The raw body is still read from the page file when you load a page. The index is only for metadata-oriented operations.

Backends #

Core ships with two index backends.

Configure the backend in config/content.php:

'drivers' => [
    'file' => [
        'index' => [
            'driver' => env('CONTENT_PAGE_INDEX_DRIVER', 'json'),
            'json' => [
                'path' => storage_path('index/page-index.json'),
            ],
            'sqlite' => [
                'path' => storage_path('index/page-index.sqlite'),
            ],
        ],
    ],
],

How syncing works #

The file driver scans content.drivers.file.path, compares each file's path and modification time against the stored index entry, and only reindexes files that changed.

That means normal page reads stay cheap after the first sync.

Rebuilding the index #

Use the CLI when you want a clean rebuild:

./velvet index:rebuild

This is useful when:

• you switch from JSON to SQLite or back
• you bulk-edit frontmatter outside the app
• an index file becomes stale or corrupted

Filters supported by the index #

The built-in file driver uses the index for these filters:

• status
• limit
• offset
• order_by
• order_dir

Valid order_by fields are:

• created_at
• updated_at
• published_at
• slug
• title
• status

Operational notes #

• JSON is a good default for smaller installs and local development.
• SQLite is usually the better choice if page listings are frequent or page counts are growing.
• The index is tenant-aware because the underlying content and storage roots are tenant-aware.