Media Directories

Media Directories adds a directory (folder) structure to Media entities and ships a modern Vue.js media browser for managing and embedding them. Folders are backed by a taxonomy vocabulary: enabling the module adds a directory field to every Media entity, so each item can be assigned to a folder and browsed in a familiar tree.

The companion Media Directories Browser submodule provides a fast, single-page Vue.js browser that integrates with CKEditor 5 for embedding media directly into content, and with media reference fields for selecting and uploading.

New 3.x version

This version is working and can be used on new installations. Previous sites using 2.x and CKEditor integration must wait until compatibility module is ready or do manual content migration.

Read more from documentation page

Compatibility module

Initial version of compatibility module is available, but it is not tested. This is only for CKEditor content.

The compatibility module only provides a layer for entity embed objects. This should be enough for most of the sites.

Content migration is not planned at the moment. This takes too much effort and could be complicated to get it right.

Features

• Folder/directory structure for Media, backed by a taxonomy vocabulary
• A directory field on every Media entity for assigning items to folders
• Vue.js media browser with drag-and-drop organization, search and quick edit
• CKEditor 5 integration for embedding media into rich text
• Integration with core Media and Media Library
• Optional AI-powered alt text generation and translation
• Optional CKEditor 5 file download links

Modules

The project is a suite — enable only the pieces you need:

• Media Directories — the base module: the directory field and Media Library integration.
• Media Directories Browser — the Vue.js media browser with CKEditor 5 embedding (the recommended editor experience).
• Media Directories File Link — a CKEditor 5 plugin for inserting file download links via the browser.
• Media Directories AI — AI-powered alt text generation and translations inside the browser (requires the AI module).
• Media Directories Compatibility — converts legacy <drupal-entity> embeds to <drupal-media> at render time; enable it on sites migrating from entity_embed-based embedding.
• Media Directories Image Resize — resizes images in text content that carry explicit width/height attributes.

Note for existing users: the older media_directories_ui (jsTree) and media_directories_editor (entity_embed) submodules are deprecated and replaced by media_directories_browser. New sites should use the Browser submodule.

Requirements

• Drupal 11 or 12 (the base module also supports 10.2, but Media Directories Browser and the submodules built on it require 11+)
• Media (core)
• Media Library (core)
• Taxonomy (core)
• Views (core)
• CKEditor 5 (core) — for Media Directories Browser and Media Directories File Link

No external JavaScript libraries are required — the browser is a bundled Vue.js application.

Installation

Install with Composer, then enable the submodules you need:

composer require drupal/media_directories

1. Enable Media Directories (and Media Directories Browser for the editor experience).
2. Create a vocabulary to hold the directory structure.
3. Select that vocabulary in the settings: /admin/config/media/media_directories

Configuration

• Browser / CKEditor 5: add the Media Directories button to the CKEditor 5 toolbar of any text format that should support media embedding (e.g. full_html at /admin/config/content/formats/manage/full_html), and make sure the Embed media and Display embedded entities filters are enabled on that format — without them, embedded media will not render.
• File Link: add the Insert file link button to the CKEditor 5 toolbar of the relevant text formats.
• AI: configure an AI provider via the AI module (add a key, choose a default provider). Alt text and translation actions then appear inside the browser.

Also review permissions: users need the appropriate Media and Taxonomy term permissions to create, move/edit and delete media and folders.

Recommended modules

• SVG image — adds SVG support to the image fields used by media types.
• Focal Point — enables focal point selection inside the media browser.
• AI — required by the Media Directories AI submodule for AI-generated alt text and translations.

Migration of an existing vocabulary

Migrating an already-existing vocabulary is not supported out of the box, as the module uses a dedicated term reference rather than a regular field. You can follow the manual approach described in #3405584: Existing term settings ignored to migrate an existing term reference on your media.

Documentation

Full documentation is published with MkDocs and hosted on GitLab Pages: https://project.pages.drupalcode.org/media_directories/

Roadmap

#3102317: [META] Roadmap