Several types of media are allowed including images, documents, audio files and content from external sources like YouTube, Vimeo, Twitter, Facebook and the University of Iowa's UI Capture (Panopto) service.

With all of these media types, you can add them from other content through fields and the WYSIWYG for display.

Each of the media types have specific documentation, but there are some shared functionality to highlight.

You can either add them directly to your site by going to Content > Media (/admin/content/media), or as you create content through fields and WYSIWYG text editors.

Replace File

When editing media from the Media overview page (admin/content/media), you have the option to overwrite the existing file. This is the default behavior and is indicated by the checked "Overwrite original file" checkbox. This will overwrite the existing file and use the same directory and filename (e.g. ../2020-09/filename.pdf). This can be useful if you have sent out hard-coded links in emails or other communications. 

If you uncheck "Overwrite original file", the media object will point to a new file with a different name. The old file, if not used elsewhere, will be deleted eventually.

Regardless of whether "Overwrite original file" is checked or not, updating a file will update any content where the media has been placed/referenced as long as it is not a hard-coded link, e.g. File fields and the WYSIWYG media button use special markup to reference media objects that is converted dynamically so you don't have to worry about updating links to files.

Deleting Media

You can delete media files through the Media overview page (admin/content/media), but there are a couple things to keep in mind.

  • We prevent deleting media that is being referenced by other content. This can include placement in WYSIWYG editors, placement in blocks or content type fields. Previous revisions also put a restriction on media deletion in case the content is reverted to that revision. Properly removing those references first will allow deleting. Layout builder blocks containing media must be deleted an not repurposed in order to release it. There is a known upstream issue related to this.
  • A warning message should be displayed with a link to the Usages tab where you can find and clean up references to the media item.
  • Once you are able to delete the media file, it is first only deleted through the UI. Editors won't be able to reference/place the media file anymore on the website.
  • The actual file on the server will still exist for about six hours until the garbage collection process runs.
  • Even after the garbage collection runs, if the file was recently fetched, the file may still be cached on the server and for browsers that previously viewed the file. Eventually these caches clear, but we understand there are situations where it needs to happen more quickly. We can trigger site-wide varnish cache clears to free this up, so contact us if you need this done.


When replacing certain media types like images and audio, the changes may not be immediately apparent. This is because browsers display a cached copy, if previously downloaded, for a period of time. People visiting your site for the first time should see the new media immediately. However, to force browsers to download the new image if previously cached, you can uncheck "Overwrite original file" when editing media.