The media library
Where all your uploaded images and documents live, and how to pick them when you’re writing.
What the library holds
The media library is the shared home for every file you’ve uploaded — cover images, inline photos, diagrams, PDFs, and any attachments you want readers to download. Find it in the dashboard sidebar under Workspace → Media.
You see your own uploads by default. Editors and admins can flip a Show all authors toggle to browse the whole library across the team.
Uploading a file
Click the Upload button above the library to open the upload box. In the box you can either:
- Click the dashed box and pick a file from your computer.
- Drag a file from your desktop and drop it on the box.
Uploads are one file at a time. The file uploads, then becomes available in the library immediately.
If you upload a file that is byte-for-byte identical to one already in your library, the library reuses the existing copy instead of adding a second one, and tells you so.
Supported types
- Images — PNG, JPG, WebP, GIF, SVG
- Documents — PDF, Word, Excel, plain text, markdown, RTF
Size limit
Light and dark versions of a figure
.on-dark.svg. The dashboard can’t upload or pair them yet; a figure added here always shows the same image on both themes.Switching views
The library has three ways to look at your media:
- Grid — a wall of thumbnails. Easiest for picking by sight.
- List — compact rows with filename, size, and upload date. Easiest for scanning a lot of files.
- Detail — larger cards with full metadata.
Use the tabs above the library to filter by type — all media, images only, or documents only. The library remembers which view you prefer.
Finding a file
Above the library you can narrow down what you see:
- Search by any part of the filename. Case does not matter.
- In use, Not in use or All — show only files something refers to, only files nothing refers to, or everything. See what counts as in use.
- The type tabs — all media, images only, or documents only.
- Sort by Newest, Oldest or Largest.
Changing any of these takes you back to the first page.
Viewing an image
Click an image in the library to open it full size. While it is open:
- Use the arrow keys, or swipe on a touch screen, to move through the images on the current page.
- Press Escape to close the viewer.
- Click Details to open the detail panel for that image.
Picking media while writing
You don’t need to visit the library directly to use something from it. The same picker opens from three places in the editor:
- Cover image button in the metadata panel — limited to images.
/imageslash command — inserts an image inline. See the slash menu./fileslash command — attaches a downloadable file inline.
Search and sort work inside the picker too. Clicking a file there still selects it.
Inside the picker you can also upload a new file — anything you upload is auto-selected so you can insert it straight away.
Paste or drop directly
Alt text for images
When you insert an inline image, the editor asks for alt text — a short description for readers who use screen readers or have images turned off. If the image is purely decorative (a separator or visual flourish), tick the decorative option instead.
Alt text is set per insertion — the same image used in two posts can have different alt text in each. Keep it under 250 characters and describe what’s in the image, not the fact that it’s an image.
Generating a cover image with AI
When picking a cover image, the picker has a Generate with AI option. Describe the subject, choose one of the curated editorial styles, and the system produces an image with no text. Generation can take up to a minute. It lands here in your library, ready to use.
For the full list of styles and the excerpt and alt-text helpers, see AI assistance.
Inspecting and removing a file
Click an image to open the viewer, then Details to open its detail panel. Documents open the detail panel directly. From there you can:
- See the filename, size, type, and upload date.
- Copy the file’s embed URL to the clipboard — useful if you want to reference it from somewhere outside the editor.
- Download the original file.
- See everything the file is currently used in, including pending edits to published posts.
- Under Other copies with this name, see other files with the same name and whether each is in use. Click View to open one.
- Delete — but only if the file isn’t in use anywhere.
Removing references first
What counts as in use
A file counts as in use when any of these refer to it:
- A post’s cover, or an image in its text, whatever the post’s status.
- Changes you have saved to a published post but not yet republished.
- The dark-theme version of a figure.
- A publication cover on an author profile.
- A series or category cover.
- A record outside the library, which the file’s Details list names only by kind: Attached to a message, Part of a post export or Used by another author’s cover generation.
Edits count straight away
Obsidian covers wait for publishing
Deleting several files
- Click Select to start choosing files.
- Tick the files you want. Files in use cannot be ticked. Select page ticks every file on the page that can be deleted.
- The bar shows how many files you have ticked and their total size. Click Delete and confirm.
If a file turns out to be in use after all, it is kept and named so you can see what was left behind.
Authors can delete only their own files. Editors and admins can also delete other authors’ unused files by turning Show all authors on.
How the URLs work
Every uploaded file gets a stable address of the form /m/{id} on the public blog. That URL never changes for the lifetime of the file, even though the underlying storage rotates the actual download link every hour or so.
That means once you’ve embedded a file in a post — or copied its URL to share elsewhere — the link keeps working indefinitely without you having to do anything.