The media library

The media library holds the images and files of a workspace: JPEG, PNG and WebP pictures, and PDF, Word, PowerPoint and Excel files. You add a file once and use it in as many documents as you like. This page shows you how to upload files, describe them, and keep them in order.

Before you start

• Open the workspace and choose Media in the top bar. The page has folders on the left, the files in the middle and the details of the file you pick on the right.
• Inside a document, the Media tab in the right column shows the same library in a small panel, for dragging pictures into the text.

What you can upload

Everything else is refused, including SVG. The CMS looks at the contents of a file, not its name, so renaming a file does not help. The limit is 25 MB per file. The setting Assets:MaxUploadBytes changes it.

What the CMS does with an upload:

• Images are re-saved. The orientation is fixed, location data and other hidden information (EXIF) are removed, and the longest side is reduced to 4096 pixels if it is larger. A small preview is made for the library.
• PDF, Word, PowerPoint and Excel files are read by a converter, and their text is stored next to the file. Search and the AI tools use it.

Upload files

1. On the Media page, choose the folder where the files should go.
2. Choose Upload, and pick one or more files. Or drag files from your computer anywhere onto the middle of the page. The overlay says where they will land.
3. A list shows the progress of each file: “Uploading photo.jpg… 40%”. A failed file shows its reason and a Dismiss button.
4. When the upload ends, the files you added are selected, and the first one opens on the right.

Expected result: the files appear in the folder. An image without alt text shows Needs alt text on its tile.

From inside a document you can also drag files into the text, or use the Media tab and choose “or choose files”. See Writing documents.

Alt text

Alt text is a short description of what an image shows, for people who cannot see it and for search engines. An image is not ready until it has alt text. Until then you cannot put it in a document, and it cannot be published.

1. Select the image. The details open on the right under Describe this image.
2. Type in Alt text. Describe what the picture shows, for example “Three red cabins by a lake at sunset”.
3. The status near the top changes from Unsaved changes to Saved. There is no save button.

Expected result: Needs alt text disappears from the tile, and the image can be used.

Tips for good alt text:

• Say what is in the picture. Do not start with “Image of” or “Picture of”. Screen readers already say it is an image. If you do, a hint appears under the field: “Screen readers already say it’s an image. Describe what it shows, e.g. ‘Three red cabins by a lake at sunset’.” It is a hint, not a rule.
• Keep it short, a sentence at most. The field takes up to 500 characters.
• An image that only decorates the page can still have a short description.

The home page lists images without alt text under Needs attention, with a link Add alt text. A second link, Review alt text, lists images whose alt text trips the hint. Both open the Media page as a work queue. See Work through a list.

A Suggest button next to Alt text can propose a description (AI suggestions).

Describe a file

For each file, the details pane has:

Every change is saved by itself as a draft. Sites see changes only after the file is published (Publishing).

The pane also shows the ID with a copy button. See Search.

The focal point

Pictures are often cropped by a site, for a banner or a card. The focal point tells it what to keep.

1. Click the part of the picture that must stay visible, such as a face. A marker shows the point.
2. Or use the sliders Focal point, horizontal and Focal point, vertical. They work with the keyboard.

By default the point is the middle of the picture.

Folders

Folders on the Media page work like the document folders (Folders and tags): the same name rules, up to 8 levels deep. They are for your own order. They are not part of any public address, and moving a file never changes anything that is published.

• New folder (button above the tree) creates a folder inside the one you are in.
• A folder’s menu has New subfolder, Rename and Delete. Delete works only on an empty folder: “Only empty folders can be deleted. Move or remove what is inside first.”
• Top level is the root. The numbers show how many files a folder holds.
• Drag files from the grid onto a folder to move them.
• Include subfolders shows the files of the folder and everything under it.

Files uploaded to a folder called Brand are published to the lake for sites to use directly. The page says so: “Files uploaded to Brand go to the lake, where sites can use them directly.” The same happens for files tagged brand. See In the lake.

Find files

Above the grid:

• Search files looks in the file name, alt text and tags.
• Filter by tag keeps files that have all the chosen tags. Pressing a tag on a tile adds it to the filter.
• The kind buttons All, Images and Files narrow by type.
• Unpublished changes shows only files with changes that are not yet published, with a count.
• The Grid and List buttons change how files are shown.
• A pager at the bottom moves between pages of 48 files.

The workspace-wide search for an ID is described in Search.

Select several files

You can act on many files at once.

When two or more files are selected, a toolbar appears with “3 selected” and these buttons:

The selection belongs to what is on screen. A new folder, filter or page starts over. With more than one file selected, the pane on the right shows the last one you picked.

Work through a list

Links on the home page open the Media page as a work queue: Images without alt text, Images with alt text to review or Files with unpublished changes. A bar shows your progress. In the pane, Previous and Next (or Alt+K and Alt+J) walk through the list. A file leaves the filter when you fix it but stays visible, marked done, so you do not lose your place. Choose Show all files to leave the queue.

In the lake

Binary files are not stored in Git. When a file is published, the CMS copies it to a public storage place, and writes a small description file into the lake. See What is mdlake?.

In the lake decides when that happens:

• Automatic (when a published document uses it): the file is in the lake while a published document uses it. This is the default.
• Always (sites can use it directly): the file is in the lake even if no document uses it. Use it for logos, brand images and downloads that a developer places on pages by ID.

A short line under the choice says where the file stands, for example “In the lake now, because a published document uses it.” or “Not in the lake yet. It is added when you publish this file.” If the file is always in the lake because of its folder or tag, it says “Always, because it’s in Brand.” or “Always, because it’s tagged brand.” Choose Reset to default to remove your own choice.

Where a file is used

Under the preview, Used in lists the documents that use the file. Each entry is a link, with the document’s state and one of:

• “In the draft and the published page”
• “Only in the published page”
• “In the draft”

“Not used in any document yet.” appears for a file nothing uses.

Remove a file

1. Select the file. Choose Move to trash in the pane, or in the toolbar for several files.
2. Confirm. In the pane, the link changes to “Really move to trash?”. For a file that is always in the lake, it reads “Remove from the lake and move to trash?”. For several files, a dialog says “They stay in the Trash for 30 days and can be restored from there.” and, for files in the lake, that moving them removes them from the lake and a restore brings them back.

The file goes to the Trash for 30 days (Trash). A Moved to the trash. line offers Undo.

A file that a document uses cannot be moved to the trash. The pane says “In use, cannot be moved to the trash”, and for several files the button is disabled with the reason: “2 of the selected files are used in documents. Remove them from the documents first.” Remove the file from the document, then publish or unpublish the document if it was published, and try again.

If something goes wrong

What’s next

• Publish files with the documents that use them: Publishing.
• Let AI draft alt text and tags: AI suggestions.