Derive descriptive, SEO-friendly storage keys from filename on upload

[swissky]

Problem

When media is uploaded, the storage key is generated as ${ulid()}${ext} (e.g. 01J7ABC...XYZ.webp) in upload-url.ts and api/media.ts. Since the public URL is derived from the storage key (storage.getPublicUrl(key) or /_emdash/api/media/file/{key}), the descriptive original filename never reaches the URL — every image is served under an opaque ULID.

Google's image SEO guidance explicitly recommends short, descriptive filenames (e.g. my-new-black-kitten.jpg over IMG00023.JPG) as a (light) signal for understanding image subject matter, and to avoid generic names. Today EmDash can't produce that signal in the URL.

Scope: new uploads only (intentionally)

The same Google guidance recommends stable, consistent image URLs (for crawl budget and caching). Renaming the keys of existing media would change URLs and break content references, so this proposal deliberately covers new uploads only — existing keys stay untouched.

Proposal

Build the storage key from a slugified filename plus a ULID suffix for uniqueness:

// e.g. "Clinique La Prairie – Pool.webp" -> "clinique-la-prairie-pool-01J7ABCXYZ.webp"
const ext = path.extname(filename);
const base = slugify(path.basename(filename, ext), 60); // existing util in utils/slugify.ts
const storageKey = base ? `${base}-${ulid()}${ext}` : `${ulid()}${ext}`;

• Backward-compatible — existing keys unchanged; only new uploads differ.
• Unique — the ULID suffix preserves collision-free keys.
• Already allowed — SAFE_STORAGE_KEY = /^[A-Za-z0-9._-]+$/ permits hyphens.
• Reuses the existing slugify() helper (handles diacritics, truncation).

Touch points

A single buildStorageKey(filename) helper in media/, used by:

• packages/core/src/astro/routes/api/media/upload-url.ts
• packages/core/src/astro/routes/api/media.ts (direct upload)
• optionally packages/core/src/astro/routes/api/import/wordpress/media.ts

Questions for maintainers

1. Default behaviour, or behind a config flag (e.g. media.descriptiveKeys)?
2. Preferred slug max length (proposed 60)?
3. Include the WordPress import path?
4. Any concern for storage providers with their own key conventions?

If the direction is welcome, I'm happy to open a small PR (with tests). A PoC is ready.

---

Disclosure: drafted with AI assistance (Cursor + Claude Opus 4.8).

[philstenning]

I do like this idea, being able to search for images in the r2 store using it's key, can make life a lot easer if you want to manually edit the bucket, but having an checkbox in a settings page would be nice if you don't want this feature.

[marcusbellamyshaw-cell]

Great idea, even better if it's wired up so we can use an AI agent to scan the media and automatically set alt text/file names for the images.

[reducedhackers]

Overall end users with WP experience are looking to have names of files that they expect; this gets a +1 for me possibly as part of the initial setup configuration options.

[swissky]

@ascorbic what do you think?

[marcusbellamyshaw-cell]

+1, this is exactly the kind of small additive change that's easy to reason about — new uploads only, existing keys untouched, reuses the existing slugify() util rather than adding a new dependency.

On the open questions: I'd default it on (no config flag) since it's purely cosmetic to the key and doesn't change behavior — a flag adds a maintenance surface for a one-line win. 60 chars for slug max sounds reasonable. I'd leave the WordPress import path out of v1 to keep the PR small; can follow up separately once the base helper lands.

@marcusbellamyshaw-c.'s AI alt-text/filename idea is a nice follow-on but a separate scope — worth its own discussion once this lands.