README

A centralized media library plugin for Kirby CMS 5 — WordPress-style asset management built directly into the Panel.

Versions

Features

V1 — Core

• Dedicated Panel area — full-screen Media Hub accessible from the Kirby sidebar
• Folder organisation — create and delete folders to keep assets tidy
• Drag-and-drop upload — upload files directly to any folder
• Full-text search — searches filename, title, alt text, description, copyright, and photographer simultaneously
• File metadata — edit title, alt text, description, copyright, photographer, and upload date per file
• mediahubpicker field — custom field type for any blueprint; works inside structure fields
• UUID-based references — saved as file://uuid — identical format to Kirby's native files field
• Usage tracking — see every page that references a given file
• Dashboard stats — total files, unused files, type breakdown, recent uploads, largest files
• Auto-refresh stats — counters update immediately after upload or delete
• No build step — pure PHP + Vue 3 template strings

V2 — Pro Smart

• 2-level subfolder support — nested folders in the sidebar with expand/collapse, breadcrumbs, correct upload URLs
• Tags & Keywords — tag files with comma-separated keywords; tag cloud in sidebar with click-to-filter
• Delete tag globally — remove a tag from all files at once with a single click (hover × on any tag)
• Smart Filtering — filter by upload date range, uploaded-by user, and file size (min/max KB)
• Bulk Operations — select multiple files → bulk delete, bulk move to folder, bulk rename (pattern file-{n}), bulk tag assignment (add / remove / replace)
• Duplicate Detection — scan for exact duplicates (MD5 hash) and similar-named files; keep oldest, newest, or shortest name with one click
• Improved picker — sidebar layout with scrollable folder tree (subfolders collapsible) + tag filter; replaces flat tab row that broke at scale
• Auto WebP conversion on upload — JPEG and PNG files are automatically converted to WebP on upload using PHP GD; original file and sidecar are replaced, UUID is preserved so all existing page references continue to work
• In-place WebP compression — existing WebP files are re-encoded at optimised quality; file is only replaced if the result is strictly smaller
• Re-optimize button — manually trigger optimization on any image from the file detail panel
• Upload progress indicator — animated progress bar and spinner shown in the drop zone while upload and optimization run; shows "Uploading & optimizing X of Y…"

Requirements

• Kirby CMS 5.0 or higher
• PHP 8.1 or higher
• PHP GD extension — required for V3 auto WebP conversion and compression (usually bundled with PHP; check with php -m | grep gd)

Installation

Via Composer (recommended)

composer require kirbycode/media-hub-pro

Manual

1. Purchase a license at kirbycode.com
2. Download the plugin zip from your account
3. Extract and copy the media-hub-pro folder into your site's site/plugins/ directory

The plugin auto-creates content/media-hub/ on the first page load — no further setup needed.

Configuration

All options go in your site's config/config.php:

return [
    // Your Media Hub Pro license key (required for V2 Pro Smart features).
    // Purchase a license at kirbycode.com — omit this key to run in Free (V1) mode.
    'kirbycode.media-hub.license' => 'MHPRO-XXXX-XXXX-XXXX-XXXX',

    // Change the slug of the hub root page (default: 'media-hub').
    // Useful if your site already has a page at that slug.
    'kirbycode.media-hub.root-slug' => 'media-hub',

    // V3 — Media Optimization (all keys optional; shown values are defaults)
    'kirbycode.media-hub.optimization' => [
        'enabled' => true,           // set to false to disable auto-conversion on upload
        'quality' => [
            'webp' => 82,            // WebP output quality (0–100)
        ],
    ],
];

Media Optimization notes (V3)

• JPEG and PNG uploads are automatically converted to WebP server-side on upload. The original file is deleted; the new .webp file carries the same UUID so all file:// references in content continue to resolve without any manual edits.
• PNG transparency is preserved during conversion.
• SVG and GIF files are never converted.
• If PHP GD is not available the upload still succeeds — no error is thrown; optimization is silently skipped.
• The Re-optimize button in the file detail panel triggers the same conversion on demand. For files already in WebP format it attempts in-place compression and reports how many bytes were saved.

Blueprint Usage

Add the mediahubpicker field type to any page or file blueprint:

Single image picker

fields:
  hero_image:
    label: Hero Image
    type: mediahubpicker
    multiple: false
    accept: image

Multi-select gallery

fields:
  gallery:
    label: Gallery
    type: mediahubpicker
    multiple: true
    accept: image
    help: Pick images from the Media Hub

Document / PDF picker

fields:
  brochure:
    label: Download
    type: mediahubpicker
    multiple: false
    accept: document

Field options

What gets saved

The field writes a standard Kirby YAML list of file:// UUIDs to the content .txt file — the same format as Kirby's built-in files field:

Hero_image:

- file://abc123def456

PHP Template Usage

Single file

$hero = $kirby->file($page->hero_image()->value());
if ($hero) {
    echo '<img src="' . $hero->url() . '" alt="' . $hero->content()->alt() . '">';
}

Multiple files / gallery

foreach ($page->gallery()->yaml() as $ref) {
    $file = $kirby->file($ref);
    if ($file) {
        echo '<img src="' . $file->url() . '" alt="' . $file->content()->alt() . '">';
    }
}

Bulk Operations (V2)

Enable Select mode in the toolbar to check multiple files, then choose an action:

Duplicate Detection (V2)

Open Duplicates from the toolbar to scan the library:

• Exact duplicates — files with identical MD5 hash
• Similar names — files with matching base names after stripping suffixes like -final, -copy, -v2, (1), etc.

For each group you can: keep the oldest, keep the newest, keep the shortest filename, or manually pick which copy to keep.

Supported File Types

How It Works

The plugin registers a Kirby content page at content/media-hub/ (auto-created on first load). Subfolders are standard Kirby child pages with the media-hub-folder template. Files use Kirby's native flat-file storage with .txt metadata sidecars.

The Panel area is a custom Kirby area with Vue 3 components (no build step — uses Kirby's bundled runtime). REST API routes under /api/media-hub/ handle all operations.

Changelog

See CHANGELOG.md.

License

Proprietary — Shivlal Sheladiya. All rights reserved. A valid license is required. Purchase at kirbycode.com.

Credits

Built with Kirby CMS by kirbycode.com.

If this plugin saves you time, consider sponsoring further development.