fix(core): RecentPosts widget links by slug and supports urlTemplate (#1332)

.changeset/recent-posts-widget-url.md

@@ -0,0 +1,6 @@
+---
+"emdash": patch
+"@emdash-cms/admin": patch
+---
+
+Adds an optional `urlTemplate` prop to the `core:recent-posts` widget (e.g. `"/blog/:slug"` or `"/:slug"` for catch-all routes), using the same `:collection`, `:id`, `:slug`, and `:path` tokens as LiveSearch's `routeMap`, with a localized label in the admin widget form. Without a template the widget links exactly as before.

docs/src/content/docs/guides/widgets.mdx

@@ -35,12 +35,14 @@ The following built-in component widgets are available:
 
 | Component | What it renders |
 | --------- | --------------- |
-| `core:recent-posts` | Recent posts, with optional dates and thumbnails |
+| `core:recent-posts` | Recent posts, with optional dates, thumbnails, and a link URL template (e.g. `/blog/:slug`) |
 | `core:categories` | Category links and optional entry counts |
 | `core:tags` | A limited list of tag links and optional counts |
 | `core:search` | A search form that submits to `/search` |
 | `core:archives` | Monthly or yearly post archive links |
 
+The `core:recent-posts` link template accepts the same tokens as LiveSearch's `routeMap`: `:collection`, `:id` (the content ULID), `:slug` (the bare slug), and `:path` (slug or ID). Without a template, links keep their existing shape, including any Astro i18n locale prefix.
+
 ## Place the area in a template
 
 Import `WidgetArea` from `emdash/ui`. The component fetches the named area, preserves the configured order, and renders nothing when the area is missing or empty.

packages/admin/src/components/Widgets.tsx

@@ -129,6 +129,7 @@ const CORE_WIDGET_META: Record<string, CoreWidgetMeta> = {
 			count: { label: msg`Number of posts` },
 			showThumbnails: { label: msg`Show thumbnails` },
 			showDate: { label: msg`Show date` },
+			urlTemplate: { label: msg`URL template (e.g. /blog/:slug)` },
 		},
 	},
 	"core:categories": {

packages/core/src/components/widgets/RecentPosts.astro

@@ -1,13 +1,17 @@
 ---
 import { getEmDashCollection } from "../../query.js";
+import { sanitizeHref } from "../../utils/url.js";
+import { buildLiveSearchResultUrl } from "../live-search-routing.js";
 
 interface Props {
 	count?: number;
 	showThumbnails?: boolean;
 	showDate?: boolean;
+	/** URL template for post links, e.g. "/blog/:slug" (tokens: :collection, :id, :slug, :path) */
+	urlTemplate?: string;
 }
 
-const { count = 5, showThumbnails = false, showDate = true } = Astro.props;
+const { count = 5, showThumbnails = false, showDate = true, urlTemplate } = Astro.props;
 
 const { entries: posts } = await getEmDashCollection("posts", {
 	limit: count,
@@ -27,6 +31,23 @@ function getString(data: Record<string, unknown>, key: string): string | undefin
 			const publishedAt = getString(post.data, "publishedAt");
 			const featuredImage = getString(post.data, "featured_image");
 			const title = getString(post.data, "title");
+			// Without a template, keep the widget's long-standing default:
+			// `post.id` is the loader's slug (or `locale/slug` with i18n
+			// prefixing), so the locale prefix is preserved. With a template,
+			// use the same token semantics as LiveSearch's routeMap — `:id`
+			// is the content ULID (`data.id`), `:slug` the bare slug.
+			const href = urlTemplate
+				? sanitizeHref(
+						buildLiveSearchResultUrl(
+							{
+								collection: "posts",
+								id: getString(post.data, "id") ?? post.id,
+								slug: getString(post.data, "slug") ?? post.id,
+							},
+							{ posts: urlTemplate },
+						),
+					)
+				: `/posts/${post.id}`;
 			return (
 				<li>
 					{showThumbnails && featuredImage && (
@@ -36,7 +57,7 @@ function getString(data: Record<string, unknown>, key: string): string | undefin
 							class="widget-recent-posts__thumbnail"
 						/>
 					)}
-					<a href={`/posts/${post.id}`} class="widget-recent-posts__link">
+					<a href={href} class="widget-recent-posts__link">
 						{title}
 					</a>
 					{showDate && publishedAt && (

packages/core/src/widgets/components.ts

@@ -25,6 +25,10 @@ export const coreWidgetComponents: WidgetComponentDef[] = [
 				label: "Show date",
 				default: true,
 			},
+			urlTemplate: {
+				type: "string",
+				label: "URL template (e.g. /blog/:slug)",
+			},
 		},
 	},
 	{

packages/core/tests/repro/recent-posts-url.render.test.ts

@@ -0,0 +1,50 @@
+import { experimental_AstroContainer as AstroContainer } from "astro/container";
+import { describe, expect, it, vi } from "vitest";
+
+import RecentPosts from "../../src/components/widgets/RecentPosts.astro";
+
+vi.mock("../../src/query.js", () => ({
+	getEmDashCollection: vi.fn(async () => ({
+		entries: [
+			{
+				// The loader's entry id is the slug, or `locale/slug` with
+				// i18n prefixing — distinct from the content ULID in data.id.
+				id: "en/hello-world",
+				data: {
+					id: "01ARZ3NDEKTSV4RRFFQ69G5FAV",
+					slug: "hello-world",
+					title: "Hello World",
+					publishedAt: "2026-01-01T00:00:00.000Z",
+				},
+			},
+		],
+	})),
+}));
+
+async function renderHref(props: Record<string, unknown>): Promise<string> {
+	const container = await AstroContainer.create();
+	const html = await container.renderToString(RecentPosts, { props, locals: {} });
+	const match = html.match(/<a href="([^"]*)"/);
+	if (!match) throw new Error(`no link in rendered widget: ${html}`);
+	return match[1]!;
+}
+
+describe("RecentPosts link URLs", () => {
+	it("keeps the locale-prefixed default without a template", async () => {
+		expect(await renderHref({})).toBe("/posts/en/hello-world");
+	});
+
+	it("substitutes the bare slug into :slug", async () => {
+		expect(await renderHref({ urlTemplate: "/blog/:slug" })).toBe("/blog/hello-world");
+	});
+
+	it("substitutes the content ULID into :id, not the slug-shaped entry id", async () => {
+		expect(await renderHref({ urlTemplate: "/posts/:id" })).toBe(
+			"/posts/01ARZ3NDEKTSV4RRFFQ69G5FAV",
+		);
+	});
+
+	it("neutralizes a template with an unsafe URL scheme", async () => {
+		expect(await renderHref({ urlTemplate: "javascript:alert(1)/:slug" })).toBe("#");
+	});
+});

packages/core/tests/unit/widgets/widgets.test.ts

@@ -508,6 +508,7 @@ describe("Widget System", () => {
 			expect(recentPosts?.props).toHaveProperty("count");
 			expect(recentPosts?.props).toHaveProperty("showThumbnails");
 			expect(recentPosts?.props).toHaveProperty("showDate");
+			expect(recentPosts?.props).toHaveProperty("urlTemplate");
 		});
 
 		it("should include categories component", () => {