URL Pattern Configuration: Design Alternatives for Published Content Links

[dcardosods]

Overview

I've noticed an inconsistency in how published content URLs are generated across starter templates. The contentUrl() function in the admin generates URLs based on collection names and optional urlPattern configuration, but there's a disconnect between these generated URLs and actual Astro routes in the templates.

Examples of the Issue

• Portfolio Template: Admin generates links to /projects/{slug}, but the Astro route is at /work/{slug}
• About Page: Admin generates links to /pages/about, but the Astro route is at /about

This results in 404s when users click the "View Published" link in the admin dashboard.

Root Cause

The contentUrl() function (in packages/admin/src/lib/url.ts) has three modes:

1. If urlPattern is provided → use it (e.g., /blog/{slug})
2. If not → default to /{collection}/{slug}
3. No validation that the generated URL actually matches the Astro routes

The starter templates don't consistently configure urlPattern for each collection, leading to mismatches.

Questions for the Maintainers

Before I submit a fix, I'd like to understand the intended design:

1. Should urlPattern be required/validated? Should the system warn users when a collection doesn't have a configured URL pattern?

2. Should URL mapping be centralized? Would it be better to:

   • Define all URL mappings in a config file that both Astro and the admin can read?
   • Have the admin pull route information dynamically from the Astro site?
   • Keep it as is (decoupled config) but improve documentation?

3. Should starter templates auto-configure this? Should urlPattern be pre-configured in starter templates to match their actual routes?

4. Should there be a fallback mechanism? If a URL pattern is missing, should the admin:

   • Show a warning instead of a link?
   • Offer a way for users to manually verify the URL before opening it?
   • Attempt to auto-detect the correct route?

Proposed Solutions

I'm considering these approaches:

• Option A: Update all starter templates to properly configure urlPattern for each collection + improve docs
• Option B: Add a config validation step that warns if urlPattern is missing
• Option C: Make URL configuration part of the CMS UI (allow users to set it per collection)
• Option D: Create a route discovery system that syncs with Astro's route definitions

Next Steps

Which approach aligns best with your vision for emdash? I'm happy to implement whichever solution the team prefers.

Thanks!

[drateberry]

Adding a fifth option to A–D, in case it's useful framing:

Option E — opt-in catch-all route driven by urlPattern.

urlPattern already feeds three consumers: the admin Preview button (#167), per-collection sitemaps (#431), and the resolveEmDashPath() helper. The one consumer missing is the Astro router itself — users who see the admin field naturally expect setting it to "do something," but today they still have to hand-roll src/pages/<path>/[slug].astro matching the pattern.

An additive integration option would close that loop:

emdash({
  contentRoutes: { entrypoint: "./src/layouts/EmDashEntry.astro" },
})

When set, the integration injects a catch-all route that calls resolveEmDashPath() and renders the user's entrypoint with { entry, collection, params } as props. Off by default; non-breaking. EmDash never imposes rendering — the user's entrypoint owns layout and component choices.

Relative to A–D this is complementary rather than competing:

• A (template-bundled patterns) starts working end-to-end instead of just making admin links match hand-rolled routes.
• B (validation/warnings) gets easier because the route is real — you can check it exists during build.
• D (sync from Astro) becomes unnecessary: the admin's urlPattern is what's routed, so the two can't drift.

Happy to prototype this for review if the direction is interesting. Filed an issue at #728 before noticing this Discussion — closing that and pointing it here.

[ascorbic]

I don't want to fight the Astro router on this. I'm open to the idea of a catch-all for default rendering, but I'm not sure this approach is right. What does it offer that adding pages/[slug...].astro with a helper would miss?

[dcardosods]

After spending more time developing with Emdash/Astro I can see that some of the ideas from OP are overkill and agree we should follow Astro router whenever possible.

Still, I went ahead and created a PR #1099 that:

• documents urlPattern
• add urlPattern and/or missing routes to the templates, to avoid 404