How to Enable Indexing of Custom File Types in Crafter Studio

CrafterCMS Studio provides powerful tools for content authors to manage and reference digital assets. However, not all file types are indexed and made available by default. This behavior is governed by the indexing configuration, and in some cases, you may need to customize it.

By default the following mimetypes are indexed:

 - application/pdf
 - application/msword
 - application/vnd.openxmlformats-officedocument.wordprocessingml.document
 - application/vnd.ms-excel
 - application/vnd.ms-powerpoint
 - application/vnd.openxmlformats-officedocument.presentationml.presentation

In this blog post, we’ll explore how to enable support for custom MIME types in CrafterCMS, using .vtt files (Web Video Text Tracks) as an example. This method can be applied to any file type you want to index and make available in the Studio UI.

Why Some Files Don’t Appear in the File Selector

When authors try to link or embed files using Studio’s file picker, only indexed content appears. By default, CrafterCMS indexes a predefined set of MIME types. If a file type isn’t listed in this set, it won’t appear, even if it exists in your /static-assets or has been uploaded to S3.

For example, .vtt files used for video captions are not included by default. This results in frustration when content teams try to select them as a "File source" in components like video players.

Solution: Extend the Supported MIME Types

CrafterCMS uses a component called Deployer to control indexing. You can override the default behavior by customizing the base-target.yaml configuration file, which defines the MIME types to be indexed.

Step-by-Step Instructions

1. Locate Your Deployer Configuration

   If you haven’t already created a custom base-target.yaml, copy the default one from the Deployer source:
   Note: If you are comfortable with YAML you can override only the elments you need which will ease upgrades in the future.

   https://github.com/craftercms/deployer/blob/develop/src/main/resources/base-target.yaml

2. Update supportedMimeTypes

   Look for the supportedMimeTypes section in the YAML file and add the MIME type you want to support. For .vtt files, the correct MIME type is:

   supportedMimeTypes:
     - text/vtt
     # add other existing types...

   If you're unsure about the MIME type of a file, you can check it using a tool like file --mime-type on Unix-based systems.

3. Deploy Your Configuration

   Place your customized base-target.yaml in your project’s config/deployer directory.

   Example path:

   <your-project-root>/config/deployer/base-target.yaml

4. Trigger a Reindex

   After updating the configuration, you must reindex your project for changes to take effect:

   • See the following documentation on initiating a re-index:
     https://craftercms.com/docs/current/by-role/system-admin/maintenance/reindexing-content.html#step-2-invoke-the-reprocessing
     

5. Verify in Studio

   Navigate to a content form or RTE where you use the "Select an item" dialog. You should now see your previously missing file types (e.g., .vtt) in the file selection modal.

Use Cases Beyond .vtt

This approach works for any MIME type, for example, Office formats like .xlsb (application/vnd.ms-excel.sheet.binary.macroEnabled.12)

Adding support is as simple as identifying the MIME type and updating the configuration.

Final Thoughts

CrafterCMS is designed to be extensible, and fine-tuning the indexing process is a key part of adapting it to your organization’s needs. By following the steps above, you ensure your content creators have access to all necessary resources within Studio, no matter the file type.

For more information, refer to the official Crafter Deployer documentation.