README

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

Versions

Version	Price	Key additions
V1 — Pro	Free	Folders, search, metadata, picker field, usage tracking, stats
V2 — Pro Smart	€40	+ 2-level subfolders, tags, smart filters, bulk operations, duplicate detection, auto WebP conversion, image compression, upload progress indicator, single-file rename

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; opens the library in a modal (works inside block and structure drawers)
Edit metadata from the page — click a file in the picker (or ✎ on a selected file) to edit title, alt text, description and tags without leaving the page; images without alt text are flagged with an ALT badge. Any user whose Kirby role may update files can save metadata
Replace file — upload a new version from the detail panel or the picker; UUID, metadata and folder are kept, so every page using the file updates (JPG/PNG onto WebP is converted automatically)
Rename file — rename a single file straight from the detail panel; the extension and the UUID are kept, so every page using the file keeps working. Restricted to the roles in kirbycode.media-hub.rename-roles (Pro)
Upload from the picker — drag files onto the picker modal or click Upload; they go into the folder selected in the sidebar (or the Media Hub root), are selected automatically and open in the details pane for alt text. Uses Kirby's own upload API, so role permissions, the upload whitelist and WebP optimization all apply. The field's accept option is respected
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

Purchase a license at kirbycode.com
Download the plugin zip from your account
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

Option	Type	Default	Description
`multiple`	bool	`true`	Allow selecting more than one file
`accept`	string	(all)	Filter picker to a type: `image`, `document`, `video`, `audio`
`label`	string	`Media Hub Files`	Panel field label
`help`	string	—	Help text shown below the field

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:

Action	What it does
Bulk Delete	Permanently deletes all selected files
Bulk Move	Moves all selected files to a chosen folder
Bulk Rename	Renames using a pattern, e.g. `photo-{n}` → `photo-1.jpg`, `photo-2.jpg`
Bulk Tag	Add / Remove / Replace tags on all selected files at once

Every action also checks the user's Kirby permissions per file (role + blueprint options): e.g. a role with files.delete: false cannot delete or move files, and those files are listed as errors instead of being changed.

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

Category	Extensions
Images	jpg, jpeg, png, gif, webp, svg, avif
Documents	pdf, doc, docx, xls, xlsx, ppt, pptx, odt, ods, odp, txt, csv
Video	mp4, mov, m4v, webm, avi
Audio	mp3, wav, ogg, m4a
Archives	zip, gz, tar
Design	ai, eps, psd

Uploads with any other extension are rejected (scripts and markup such as .js, .xml or .html can never be uploaded). To change the list, set kirbycode.media-hub.accept — it replaces the file blueprint's accept option:

'kirbycode.media-hub.accept' => [
    'extension' => ['jpg', 'jpeg', 'png', 'webp', 'svg', 'pdf', 'mp4'],
    'maxsize'   => 10 * 1024 * 1024, // 10 MB
],

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

Credits

Built with Kirby CMS by kirbycode.com.

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

kirbycode / media-hub-pro

Package info

Security

Statistics