Media Library

Upload, insert, reuse, replace, and delete images, videos, and files in your documentation, from the web editor or from a Git repository.

The media library stores every image, video, PDF, and file you upload to documentation. Each file gets a permanent URL you can insert, reuse, and replace from the web editor or reference in MDX. The library keeps one copy of every file, so duplicate uploads are detected and reused automatically.

Before you begin

• You need the Editor or Admin role to upload, insert, or replace files. Only Admins can delete files.
• Check that the file is a supported type and within your plan's size limit. See Limits and supported file types.
• If you work in Git, keep the documentation open in the web editor as well. Files are uploaded there, not committed to the repository.

Web editor

How to upload a file

Open the Media tab

In the web editor, select Media in the secondary navigation bar. Files already in this documentation appear as tiles.

Add the file

Click Upload media and choose the file, or drag it from your computer onto the Media tab.

If you want to upload several files at once, select or drag them together. Each one shows its own progress in the tray at the bottom-right.

Describe the image

If the file is an image, the editor shows Describe this file. Type what the image shows and click Save. This becomes the alt text that screen readers read.

If the image is decorative, click Skip.

The Media tab. Hover a tile to insert it, copy its URL, or open it.

If the editor says "That file is already in your library", the existing file is reused. You do not need to do anything.

If you would rather upload while inserting, use the Upload tile in the /image, /video, or /file picker instead. See How to add an image, video, or file to a page.

How to add an image, video, or file to a page

Open the page first. Insert always goes into the page that is currently open.

Then use whichever method suits what you are doing:

• If the file is already in the library, hover its tile in the Media tab and click Insert into page (images and videos) or Insert link into page (everything else). Or drag the tile onto the page and drop it where you want it.
• If you are typing and want to add something in place, type / on an empty line and choose:
  • Image for a screenshot, diagram, or logo
  • Video for a video file, or a YouTube, Vimeo, or Loom link
  • File for a PDF, spreadsheet, presentation, ZIP, audio clip, or font In the picker, select a tile or click Upload to add a new file, then click Insert.
• If the file is still on your computer, drop it onto the page or paste it from the clipboard. An image opens a small dialog so you can name it and add alt text. Any other supported file uploads and appears as a link at the drop point.

What lands on the page depends on the kind of file:

To adjust size, alignment, or captions after inserting, see Images and Videos and iframes.

How to reuse a file on another page

Open the other page, then insert the file from the Media tab or the slash-command picker as described above. Do not upload it again. Every page that uses the file points at the same URL, so a later replacement updates all of them together.

How to find a file

If the Media tab shows too many tiles, type part of the file name in the search box at the top.

If you need filters or a list view, click the expand icon in the tab header ( Open the media library). In the Media library window you can:

• Search by file name or alt text
• Filter by Type (Images, Video, Documents, Data, Audio, Archives, Fonts), Size, or Added date
• Sort by Newest, Oldest, Name, or Largest
• Switch to List view to see name, type, and date in columns
• Change Show to load 30, 60, or 120 files at a time, and click Load more for the next batch

The Media library window with filters, sorting, and view controls.

Click any tile to open its detail panel.

The detail panel. Edit alt text, copy the URL, or insert, replace, and delete the file.

How to change a file's alt text or link text

1. Click the file's tile to open the detail panel.
2. Edit the field at the top:
   • For an image, this is Alt text.
   • For any other file, this is Description. It is used as the link text the next time someone inserts the file.
3. Click Save alt text.

Changing the description does not rewrite links already on pages. If you want to change existing link text, edit it on the page like any other link.

How to update a file everywhere it is used

Use Replace file when you have a newer version of a file. Every page that uses it shows the new version without any edits to those pages.

Open the file

Click the file's tile in the Media tab or the Media library window to open its detail panel.

Choose the replacement

Click Replace file and choose the new file. It must be the same type as the original, for example a PNG for a PNG or a PDF for a PDF.

If you need to switch formats, insert the new file separately and remove the old one instead.

Wait for the confirmation

A toast shows Uploading…, then Replacing across your documentation…, then File replaced.

If the file is an image, its tile shows a Replacing overlay for up to a minute while the CDN refreshes. Reload a page after that to see the new version.

If you see "Someone else replaced this file first", reload and check the current version before replacing again.

How to delete a file

Admin only. Deletion does not check whether pages still use the file. Pages keep working, but the deleted image, video, or link target shows as missing. If you only need newer content, use Replace file instead.

• To delete one file, open its detail panel, click Delete, and confirm.
• To delete several files, open the Media library window, hover tiles and tick their checkboxes (or click Select all), click Delete in the bar at the bottom, and confirm. You can delete up to 100 files at once.

Deleting frees storage immediately.

How to see who uploaded, replaced, or deleted a file

You must be an organization admin.

1. Open the Media library window from the Media tab.
2. Click Activity in the bottom bar. Each entry shows the action, the file, the person, and the time.
3. If you need the list outside the dashboard, click Export CSV.

The Activity panel records every upload, replace, and delete.

Code editor (Git)

Media files are not committed to your repository. You upload them in the dashboard, then reference their URLs in .mdx files. For the branch and pull request flow around those edits, see Code editor.

How to get a file's URL

1. Open the documentation in the web editor and select the Media tab.
2. If the file is not there yet, click Upload media and add it. You do not need to insert it into a page.
3. Hover the tile and click Copy URL.

How to add an image or file in MDX

Paste the URL into the component that matches the kind of file. These are the same snippets the web editor writes.

If you want an image:

<Image
  src="https://blob-cdn.documentation.ai/org-53a37986-2c9e-4094-b9e8-1e1ffae9e9ee/doc-b389b141-ae58-4fd5-91f9-6702fae9ac58/1788844659125-k7m4msitaol-media-tab-hover-actions.png"
  alt="Media tab in the web editor with a hovered tile"
  width="572"
  height="505"
/>

Renders as:

If you want readers to open or download a file, write a Markdown link:

[Open the demonstration (PDF)](https://file-cdn.documentation.ai/org-53a37986-2c9e-4094-b9e8-1e1ffae9e9ee/doc-b389b141-ae58-4fd5-91f9-6702fae9ac58/1788846660209-arams5u6ft-demonstration.pdf)

Renders as:

Open the demonstration (PDF)

Commit and push as usual. The file is already hosted, so it renders as soon as the build completes. For all props, see Images and Files. For video, see Videos and iframes.

How to update a file without changing your MDX

Replace it in the web editor. Open the Media tab, click the file, click Replace file, and choose the new version of the same type. The URL stays the same, so no commit is needed. See How to update a file everywhere it is used.

How to swap or remove a file

• If you want a different file, upload it, copy its URL, and change the src or link target in your MDX. The old file stays in the library until an admin deletes it.
• If you want to remove a file entirely, delete every reference in MDX first, publish, then ask an admin to delete the file from the library.

Common questions

Does replacing a file change its URL?

Why does the editor say a file is already in my library?

Can I organize files into folders or add tags?

What happens when I delete a file that pages still use?

Can I upload files directly in Git?

Who can delete files?

How to check storage usage

1. Go to Settings → Organization Settings → Media Storage.
2. Read Storage used for how much of your quota is in use and how much remains.
3. If you are an admin and want to know which documentation uses the most space, read Usage by documentation.

For per-file size limits by plan and file type, see Limits and supported file types below.

Media Storage in organization settings.

If usage is above 80%, a warning also appears in the media library. If you go over the limit, free space by deleting files or upgrade the plan. Uploads and publishing pause until you are under the limit; sites you have already published keep serving. See Limits and supported file types.

If an upload is refused

The message in the upload tray tells you why. Match it below:

• "A file named "…" already exists in this documentation": Rename the file, or use the existing one from the library.
• "File size exceeds your plan's limit of …MB": Compress or resize the file. For video and documents, the message names the cheapest plan that accepts it.
• "Storage limit reached": Delete unused files or upgrade. See How to check storage usage.
• "The file extension of "…" does not match its content": The file is not really the type its name says. Re-export it in the intended format.
• "Files of this type cannot be uploaded": Programs, scripts, macro-enabled Office files, and HTML are never accepted. Put them in a ZIP if readers need them.
• "SVG contains …": Remove the script or embedded content from the SVG, or export a PNG instead.
• "Uploading … files is not available yet": Delivery for that kind of file is not enabled in your environment. Contact support.

Limits and supported file types

Each plan sets a maximum size per file and a total storage quota shared by every documentation in the organization.

AppSumo Tier 1 and Tier 2 use the Standard limits. AppSumo Tier 3 and Tier 4 use the Professional limits. Images are capped at 10 MB on every plan.

Never accepted, on any plan: programs and installers (.exe, .msi, .dmg, .apk, .jar), scripts (.js, .sh, .ps1, .bat), macro-enabled Office files (.docm, .xlsm, .pptm), and web pages (.html, .htm). Uploads are verified on the server: the file's contents must match its extension, and SVG files containing scripts or embedded documents are rejected.