How documents work

Use containers, or media entities, to easily update a document linked in multiple places.


Authors should be able to create something once and reuse it in multiple places. Instead of updating the document on each page, you should only need to do it once, and your document will be up-to-date wherever it lives on the website. In some places, this works great today. In other places, it’s a work in progress, and you’ll probably need to do some manual work.

To understand documents on, it helps to learn the difference between a “file” and a “media entity,” since you’ll be working with both.

File means what you think it means: A Microsoft Word document or a .pdf, for example.

A media entity is a container for a file and for the information associated with that file. (This associated information is called “metadata,” and it helps makes documents easier to find for content managers and constituents.) When you add a download, you’re linking your content to the media entity.

You can edit the data contained in a media entity just as you can edit a content type. On the “All documents” menu, click “edit” to open a media entity in edit mode:

Once you’ve opened the media entity, you can change the data it contains, such as its title and the organization it is associated with. You can also change the file it contains:

Replacing the file inside the media entity will cause the file to update anywhere you’ve linked to the media entity on