Media Library

The media library stores every image, video, PDF, and file you upload to a 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.

Web editor

How to upload a file

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

Click any tile to open its detail panel.

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.

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

How to delete a file

• 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.

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

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.

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.

Related