Media

The Media library is the workspace's pool of uploaded files — images, video, and PDFs that posts and pages reference, plus author avatars. You upload here once and reference the resulting media row from anywhere it's needed: a post's featured image, an image block in the body, an author's avatar.

You need media:read to view the library and media:write to upload, edit, or delete files.

The Media page

Open Media from the workspace sidebar. You'll see a grid of tiles, one per file. Each tile shows a thumbnail (for images and PDFs), the file name or alt text, the file size, and the upload date.

From the top of the page you can:

• Search — case-insensitive across alt text and caption.
• Filter by type — images, video, PDFs, or all.
• Click a tile — opens the media viewer (preview, metadata, edit, delete actions).
• Upload — drag-and-drop files anywhere on the page, or click the upload button to pick from a file dialog.

Uploading

Drop files onto the page, or click Upload and pick from a file dialog. Each file uploads independently — a per-file progress bar shows during the upload, and the tile appears in the grid the moment its upload finishes.

Allowed file types

Files outside this list are rejected with a 415 error and never reach storage.

Size limit

10 MB per file in v1. Larger files are rejected with a 413 error.

For very large hero images, run them through an image optimiser (e.g. squoosh, ImageOptim) before upload — most JPEGs above 1 MB are safe to compress noticeably without visible loss. WebP is usually smaller than JPEG for the same quality.

Where the file goes

Each upload is stored in workspace-scoped object storage at workspaces/<workspaceId>/<uuid>.<ext>. The dashboard gets back a media row with:

• id — UUID. What block / featured / avatar references use.
• url — the resolved public URL. What consumers fetch from. Never embed this URL in your own templates — fetch the media via mediaId from a post or author response so the URL stays correct if the row ever changes.
• mimeType, sizeBytes, optionally width / height (when extractable).
• alt, caption — empty at upload time; fill them via the edit dialog (see below).

Editing alt text and caption

Click a tile to open the viewer, then Edit details. Two fields:

These two fields are the only metadata you can edit on a media row. You cannot swap the underlying file — to "replace" a file, delete the media row and upload a new one (and update any block / featured / avatar references to the new id).

How image edits work in the post editor

When you crop, resize, or re-aspect an image inside a post's block editor, Clog does not modify the original media row. Instead:

1. The edited result is uploaded as a new media row.
2. The image block in the post repoints to the new row's id.
3. The original media row stays in the library, unchanged, ready to be reused elsewhere (a different crop, a different post, an author avatar).

You'll see both the original and the edits in the Media library. To clean up, delete the unused ones — but only after confirming nothing else references them.

This is intentional: it means the same source image can power a square thumbnail, a wide hero, and a portrait avatar without you having to upload three separate originals. Each edit lives as its own row.

Deleting a media row

The Delete action removes the row and the underlying storage object.

For safety: search the workspace for any post or page using a media item (alt text or caption substring) before deleting it. The dashboard's media viewer also shows a list of known references when available.

What media isn't

A few things media library is not in v1 — saves you reaching for them:

• Not a file CDN. It's the place posts pull from, not a public dump for arbitrary downloads. If you need to host static assets for general use (favicons, downloadable PDFs unrelated to posts, etc.), host them on your own infrastructure.
• No folders. v1 doesn't support folders or media collections. Use alt text and caption to organise (search across both works well in practice).
• No focal-point or responsive variants. The file you upload is the file consumers fetch. If you need responsive variants, generate them on your consumer side at build time.
• No automatic compression. Optimise your files locally before upload — Clog stores what you send.

Allowed permission gates

The Post editor implicitly needs media:read to show the picker; it doesn't require media:write (a posts:write member who isn't a media:write member can still pick existing media to embed — they just can't upload new files from inside the editor).

Where to next

• Posts — image blocks, featured images, and the image-edit rule.
• Authors — where avatars live.
• Workspaces — the brand logo lives separately from Media (managed on the workspace's Branding tab).