Installation¶

This page covers what you need before installing Media Directories, the optional packages we recommend, and the configuration steps required to get a working setup.

Requirements¶

Drupal core¶

Drupal: 11 or 12 (the base module also supports 10.2, but media_directories_browser and the submodules built on top of it require 11+)
PHP: as required by your Drupal core version

Core modules¶

The base media_directories module depends on the following Drupal core modules:

media
media_library
taxonomy
views

media_directories_browser additionally depends on core jsonapi and ckeditor5.

Submodule requirements¶

Each submodule pulls in its own dependencies. Only enable the ones you need.

Submodule	Additional dependencies
`media_directories_browser`	core `jsonapi`, core `ckeditor5`
`media_directories_file_link`	`media_directories_browser`, core `ckeditor5`
`media_directories_ai`	`media_directories_browser`, AI
`media_directories_compat`	core `media` only — enable on sites migrating from `entity_embed`-based embeds.
`media_directories_image_resize`	core `filter`, core `image`

Suggested dependencies¶

These are not strictly required but they make Media Directories considerably more useful. The first three are also listed in the module's composer.json under suggest.

Package	Why you'd want it
`drupal/svg_image`	Adds SVG support to image fields used by media types.
`drupal/focal_point`	Enables focal point selection inside the media browser.
`drupal/ai`	Required by `media_directories_ai` for AI-generated alt text and translations.
`drupal/admin_toolbar`	Lets you hide core's Media overview so editors only see the directory browser.

Installing the module¶

We recommend installing via Composer:

composer require drupal/media_directories

Then enable the submodules you need:

# Just the directory field + Media Library integration
drush en media_directories

# The Vue.js browser with CKEditor 5 integration
drush en media_directories_browser

# Optional: file download links inside CKEditor 5
drush en media_directories_file_link

# Optional: AI-generated alt text and translations
drush en media_directories_ai

Which submodule should I enable?

media_directories on its own adds the directory field and Media Library integration.
media_directories_browser is the recommended editor experience — Vue.js browser with built-in CKEditor 5 embedding.
Add media_directories_file_link and/or media_directories_ai on top of the browser as needed.

Important configurations¶

`media_directories` (base module)¶

Create a vocabulary that will hold the directory structure (for example media_directories).
Select that vocabulary at /admin/config/media/media_directories so the module knows which vocabulary represents your folders.

`media_directories_browser`¶

Make sure your text format (for example full_html) has the "Embed media" and "Display embedded entities" filters enabled at /admin/config/content/formats/manage/full_html — without them embedded media will not render.
In the same text format's CKEditor 5 toolbar, add the Media Directories button so editors can open the Vue.js browser and embed media.
JSON:API must remain enabled — the browser uses it as its backend.

`media_directories_file_link`¶

Add the Insert file link button to the CKEditor 5 toolbar of any text format that should support file download links.

`media_directories_ai`¶

Configure an AI provider via the AI module (set up a key, choose a default provider, etc.).
After enabling, alt text generation and translation actions appear inside the Vue.js browser.

`media_directories_compat` (only when migrating)¶

Enable this on sites that previously used entity_embed-based media embeds. It rewrites legacy <drupal-entity> markup to <drupal-media> at render time, so you don't have to update existing content.

Verifying the install¶

Visit /admin/config/media/media_directories and confirm your vocabulary is selected.
Open a CKEditor 5 instance with the configured text format and confirm the Media Directories button is present and opens the Vue.js browser.
(If _ai is enabled) Confirm the alt text / translation actions appear in the browser's media detail view.