@lupinum/ginko-docs 0.2.3 → 0.3.0-rc.1

package/content.ts

@@ -11,6 +11,17 @@ import { routeSlugs } from "./shared/route-slugs";
 
 const isoDate = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Expected an ISO date (YYYY-MM-DD)");
 const nonEmptyString = z.string().trim().min(1);
+/** Former public URLs of a page, as served: locale prefix and translated slugs included. */
+const redirectFrom = z
+  .array(nonEmptyString.regex(/^\//, "redirectFrom entries must be absolute site paths"))
+  .optional();
+
+/**
+ * Derives the sitemap lastmod from the authored date so it has one source of
+ * truth. Route records require normalized UTC ISO values.
+ */
+const withSitemapLastmod = <T extends object>(data: T, lastmod: string | undefined) =>
+  lastmod ? { ...data, sitemap: { lastmod: `${lastmod}T00:00:00.000Z` } } : data;
 
 export interface GinkoDocsContentOptions {
   site: {
@@ -28,6 +39,7 @@ const docsSchema = z.object({
   icon: z.string().optional(),
   badge: z.string().optional(),
   updated: isoDate.optional(),
+  redirectFrom,
   sidebar: z.enum(["section", "group"]).optional(),
   navigation: z
     .object({
@@ -38,6 +50,9 @@ const docsSchema = z.object({
     })
     .optional(),
 });
+const docsSchemaWithLastmod = docsSchema.transform((data) =>
+  withSitemapLastmod(data, data.updated),
+);
 const blogSchema = z.object({
   title: z.string(),
   description: z.string(),
@@ -46,7 +61,9 @@ const blogSchema = z.object({
   readingTime: nonEmptyString,
   author: reference("authors"),
   image: z.string().optional(),
+  redirectFrom,
 });
+const blogSchemaWithLastmod = blogSchema.transform((data) => withSitemapLastmod(data, data.date));
 const authorsSchema = z.object({
   slug: z.string(),
   name: z.string(),
@@ -56,8 +73,8 @@ const authorsSchema = z.object({
   links: z.array(z.object({ label: z.string(), href: z.string() })).optional(),
 });
 
-type DocsCollection = ContentCollectionConfig<typeof docsSchema>;
-type BlogCollection = ContentCollectionConfig<typeof blogSchema>;
+type DocsCollection = ContentCollectionConfig<typeof docsSchemaWithLastmod>;
+type BlogCollection = ContentCollectionConfig<typeof blogSchemaWithLastmod>;
 type AuthorsCollection = ContentCollectionConfig<typeof authorsSchema>;
 type DocsContentConfig = ContentConfig<{ docs: DocsCollection }>;
 type DocsBlogContentConfig = ContentConfig<{
@@ -100,7 +117,7 @@ export function defineGinkoDocsConfig(
     route: i18n ? routeSlugs.docs : routeSlugs.docs.en,
     agent: { section: "optional", markdown: true },
     strict: true,
-    schema: docsSchema,
+    schema: docsSchemaWithLastmod,
   });
   const blog = defineCollection({
     type: "page",
@@ -109,7 +126,7 @@ export function defineGinkoDocsConfig(
     route: i18n ? routeSlugs.blog : routeSlugs.blog.en,
     agent: { section: "blog", markdown: true },
     strict: true,
-    schema: blogSchema,
+    schema: blogSchemaWithLastmod,
   });
   const authors = defineCollection({
     type: "data",

package/i18n/messages/global/docs.ts

@@ -17,6 +17,7 @@ export const docs = {
   showAllLines: { de: "Alle {count} Zeilen anzeigen", en: "Show all {count} lines" },
   showMore: { de: "Mehr anzeigen", en: "Show more" },
   zoomImage: { de: "Bild vergrößern", en: "Zoom image" },
+  lastUpdated: { de: "Zuletzt aktualisiert", en: "Last updated" },
   moreActions: { de: "Weitere Seitenaktionen", en: "More page actions" },
   copyLink: { de: "Markdown-Link kopieren", en: "Copy Markdown link" },
   viewMarkdown: { de: "Als Markdown anzeigen", en: "View as Markdown" },

package/i18n/messages/global/nav.ts

@@ -17,6 +17,5 @@ export const nav = {
   company: { de: "Unternehmen", en: "Company" },
   documentation: { de: "Dokumentation", en: "Documentation" },
   blog: { de: "Blog", en: "Blog" },
-  github: { de: "GitHub", en: "GitHub" },
   externalLink: { de: "externer Link", en: "external link" },
 } as const;

package/icon-bundle.ts

@@ -79,68 +79,16 @@ export const layerIconNames = [
   "lucide:zap",
 ] as const;
 
-type IconTransform = {
-  width?: number;
-  height?: number;
-  left?: number;
-  top?: number;
-  rotate?: number;
-  hFlip?: boolean;
-  vFlip?: boolean;
-};
-type IconData = IconTransform & { body: string };
-type IconAlias = IconTransform & { parent: string };
 type IconCollection = {
   prefix: string;
   width?: number;
   height?: number;
-  icons: Record<string, IconData>;
-  aliases?: Record<string, IconAlias>;
+  icons: Record<string, { body: string }>;
+  aliases?: Record<string, { parent: string }>;
 };
 
 const require = createRequire(import.meta.url);
-const sourceCollections = new Map<string, IconCollection>(
-  ["circle-flags", "logos", "lucide"].map((prefix) => [
-    prefix,
-    require(`@iconify-json/${prefix}/icons.json`) as IconCollection,
-  ]),
-);
-
-export const layerIconCollections: IconCollection[] = [...sourceCollections.values()].map(
-  ({ prefix, width, height }) => ({ prefix, width, height, icons: {}, aliases: {} }),
-);
 
-const bundledCollections = new Map(
-  layerIconCollections.map((collection) => [collection.prefix, collection]),
+export const layerIconCollections = ["circle-flags", "logos", "lucide"].map(
+  (prefix) => require(`@iconify-json/${prefix}/icons.json`) as IconCollection,
 );
-
-function includeIcon(prefix: string, name: string, seen = new Set<string>()) {
-  const key = `${prefix}:${name}`;
-  if (seen.has(key)) return;
-  seen.add(key);
-
-  const source = sourceCollections.get(prefix);
-  const target = bundledCollections.get(prefix);
-  if (!source || !target) return;
-
-  const icon = source.icons[name];
-  if (icon) {
-    target.icons[name] = icon;
-    return;
-  }
-
-  const alias = source.aliases?.[name];
-  if (!alias) return;
-  target.aliases![name] = alias;
-  includeIcon(prefix, alias.parent, seen);
-}
-
-export function includeIconNames(names: Iterable<string>) {
-  for (const icon of names) {
-    const separator = icon.indexOf(":");
-    if (separator < 1) continue;
-    includeIcon(icon.slice(0, separator), icon.slice(separator + 1));
-  }
-}
-
-includeIconNames(layerIconNames);

package/modules/feature-routing.ts

@@ -1,10 +1,16 @@
 import { defineNuxtModule } from "@nuxt/kit";
 import type {} from "@lupinum/ginko-content";
+import { localeCodes, localizedPath } from "../i18n/locales";
+import { routeSlugs } from "../shared/route-slugs";
 
 interface PageRoute {
   path: string;
 }
 
+export const blogFeedRoutes = localeCodes.map(
+  (locale) => `${localizedPath(locale, routeSlugs.blog[locale])}/rss.xml`,
+);
+
 export function removeBlogPages(pages: PageRoute[], blogEnabled: boolean) {
   if (blogEnabled) return;
 
@@ -28,5 +34,14 @@ export default defineNuxtModule({
     nuxt.hook("pages:extend", (pages) => {
       removeBlogPages(pages, blogEnabled);
     });
+
+    // content:context runs before Nitro config is finalized, so the feed
+    // routes only prerender when the consuming app enables the blog.
+    nuxt.hook("nitro:config", (nitroConfig) => {
+      if (!blogEnabled) return;
+      nitroConfig.prerender ??= {};
+      nitroConfig.prerender.routes ??= [];
+      nitroConfig.prerender.routes.push(...blogFeedRoutes);
+    });
   },
 });

package/nuxt.config.ts

@@ -6,7 +6,9 @@ import darkPlus from "shiki/dist/themes/dark-plus.mjs";
 import lightPlus from "shiki/dist/themes/light-plus.mjs";
 import { contentComponentPolicy, contentComponentTags } from "./tags";
 import { i18nPages } from "./i18n/routes";
-import { includeIconNames, layerIconCollections, layerIconNames } from "./icon-bundle";
+import { localeCodes, localizedPath } from "./i18n/locales";
+import { routeSlugs } from "./shared/route-slugs";
+import { layerIconCollections, layerIconNames } from "./icon-bundle";
 
 const root = dirname(fileURLToPath(import.meta.url));
 const app = join(root, "app");
@@ -41,7 +43,7 @@ export default defineNuxtConfig({
   },
   mcp: {
     name: "Ginko Docs",
-    version: "0.2.3",
+    version: "0.3.0-rc.1",
   },
   components: {
     dirs: [
@@ -57,6 +59,7 @@ export default defineNuxtConfig({
           "SiteLocaleSwitcher.vue",
           "SiteLogoMark.vue",
           "SiteSkipLink.vue",
+          "SiteSocialLinks.vue",
         ],
       },
       {
@@ -115,13 +118,16 @@ export default defineNuxtConfig({
   },
   content: {
     componentPolicy: contentComponentPolicy,
+    // Broken internal links and missing #anchors fail the build instead of
+    // only landing in the validation report.
+    validation: "error",
     i18n: {
       translatedSlugs: true,
     },
     markdown: {
       plugins: [
         [
-          "highlight",
+          "shiki",
           {
             preStyles: false,
             transformers: [transformerNotationDiff(), transformerNotationHighlight()],
@@ -141,6 +147,9 @@ export default defineNuxtConfig({
   },
   sitemap: {
     excludeAppSources: ["nuxt:prerender"],
+    // The docs roots prerender as redirects to the first docs page; a sitemap
+    // must not list redirecting URLs.
+    exclude: localeCodes.map((locale) => localizedPath(locale, routeSlugs.docs[locale])),
   },
   app: {
     head: {
@@ -151,9 +160,6 @@ export default defineNuxtConfig({
     },
   },
   hooks: {
-    "icon:clientBundleIcons"(icons) {
-      includeIconNames(icons);
-    },
     "components:dirs"(dirs) {
       const defaultComponentsDir = join(app, "components").replaceAll("\\", "/");
       const filtered = dirs.filter((entry) => {
@@ -171,7 +177,15 @@ export default defineNuxtConfig({
       concurrency: 1,
       crawlLinks: true,
       failOnError: true,
-      routes: ["/llms.txt", "/llms-full.txt", "/sitemap.xml", "/robots.txt"],
+      routes: [
+        "/llms.txt",
+        "/llms-full.txt",
+        "/sitemap.xml",
+        "/robots.txt",
+        // Link page over every authored redirectFrom source; crawling it
+        // materializes the redirect stubs.
+        "/api/_ginko-docs/redirects",
+      ],
     },
   },
   vite: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lupinum/ginko-docs",
-  "version": "0.2.3",
+  "version": "0.3.0-rc.1",
   "description": "A Nuxt documentation layer powered by Ginko Content.",
   "keywords": [
     "content",
@@ -9,14 +9,14 @@
     "markdown",
     "nuxt"
   ],
-  "homepage": "https://github.com/Mat4m0/lupinum-docs-shadcn#readme",
+  "homepage": "https://ginko-docs.lupinum.com",
   "bugs": {
-    "url": "https://github.com/Mat4m0/lupinum-docs-shadcn/issues"
+    "url": "https://github.com/lupinum-dev/ginko-docs/issues"
   },
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Mat4m0/lupinum-docs-shadcn.git",
+    "url": "git+https://github.com/lupinum-dev/ginko-docs.git",
     "directory": "layer"
   },
   "files": [
@@ -52,37 +52,37 @@
   },
   "dependencies": {
     "@iconify-json/circle-flags": "^1.2.10",
-    "@iconify-json/logos": "^1.2.11",
-    "@iconify-json/lucide": "^1.2.111",
+    "@iconify-json/logos": "^1.2.12",
+    "@iconify-json/lucide": "^1.2.123",
     "@nuxt/fonts": "^0.14.0",
-    "@nuxt/icon": "^2.2.3",
-    "@nuxt/image": "^2.0.0",
-    "@nuxt/kit": "^4.4.7",
-    "@nuxt/scripts": "^0.13.2",
-    "@nuxtjs/color-mode": "^4.0.0",
-    "@nuxtjs/i18n": "^10.4.0",
-    "@nuxtjs/mcp-toolkit": "0.17.2",
-    "@nuxtjs/robots": "^6.1.2",
-    "@nuxtjs/sitemap": "^8.2.2",
-    "@resvg/resvg-js": "^2.6.0",
-    "@shikijs/transformers": "^4.2.0",
-    "@tailwindcss/vite": "^4.3.0",
-    "@vueuse/core": "^14.2.1",
+    "@nuxt/icon": "^2.5.0",
+    "@nuxt/image": "^2.1.0",
+    "@nuxt/kit": "^4.5.2",
+    "@nuxt/scripts": "^1.3.3",
+    "@nuxtjs/color-mode": "^4.0.1",
+    "@nuxtjs/i18n": "^10.6.0",
+    "@nuxtjs/mcp-toolkit": "0.18.1",
+    "@nuxtjs/robots": "^6.1.4",
+    "@nuxtjs/sitemap": "^8.3.4",
+    "@resvg/resvg-js": "^2.6.2",
+    "@shikijs/transformers": "^4.4.3",
+    "@tailwindcss/vite": "^4.3.3",
+    "@vueuse/core": "^14.4.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "motion-v": "^2.3.0",
     "nitropack": "^2.13.4",
-    "nuxt-og-image": "^6.7.2",
-    "reka-ui": "^2.9.2",
-    "satori": "^0.19.2",
-    "shiki": "^4.0.2",
-    "tailwind-merge": "^3.5.0",
-    "tailwindcss": "^4.2.2",
+    "nuxt-og-image": "^6.7.8",
+    "reka-ui": "^2.10.3",
+    "satori": "^0.19.3",
+    "shiki": "^4.4.3",
+    "tailwind-merge": "^3.6.0",
+    "tailwindcss": "^4.3.3",
     "tw-animate-css": "^1.4.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@lupinum/ginko-content": ">=0.3.2 <0.4.0",
+    "@lupinum/ginko-content": ">=0.4.0-rc.1 <0.5.0",
     "nuxt": ">=4.4.7 <5",
     "vue": "^3.5.35",
     "vue-router": "^5.1.0"

package/server/api/_ginko-docs/redirects.get.ts

@@ -0,0 +1,28 @@
+import { defineEventHandler, setHeader } from "h3";
+import { loadRedirectMap } from "../../utils/redirects";
+
+const escapeHtml = (value: string) =>
+  value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+
+/**
+ * Prerender seed: returns a link page of every `redirectFrom` source so the
+ * crawler visits each old path and materializes its redirect stub. Conflict
+ * validation throws here, which fails the build via `failOnError`.
+ */
+export default defineEventHandler(async (event) => {
+  const redirects = await loadRedirectMap(event);
+
+  if (import.meta.prerender) {
+    setHeader(event, "content-type", "text/html; charset=utf-8");
+    const links = Array.from(redirects.keys())
+      .map((source) => `<a href="${escapeHtml(source)}"></a>`)
+      .join("");
+    return `<!doctype html><html><head><meta charset="utf-8"></head><body>${links}</body></html>`;
+  }
+
+  return { count: redirects.size, redirects: Object.fromEntries(redirects) };
+});

package/server/middleware/redirects.ts

@@ -0,0 +1,22 @@
+import { defineEventHandler, sendRedirect } from "h3";
+import { loadRedirectMap } from "../utils/redirects";
+import { normalizeRedirectPath } from "../utils/redirects.utils";
+
+/**
+ * Serves authored `redirectFrom` moves as 301s. During prerender this runs
+ * before the catch-all page would SSR a 404 for the crawled old path, so the
+ * static build materializes the same meta-refresh stub the docs root uses.
+ */
+export default defineEventHandler(async (event) => {
+  if (event.method !== "GET" && event.method !== "HEAD") return;
+
+  const path = normalizeRedirectPath(event.path);
+  const lastSegment = path.slice(path.lastIndexOf("/") + 1);
+  if (path.startsWith("/api/") || path.startsWith("/_") || lastSegment.includes(".")) return;
+
+  const redirects = await loadRedirectMap(event);
+  const target = redirects.get(path);
+  if (target) {
+    return sendRedirect(event, target, 301);
+  }
+});

package/server/routes/[locale]/blog/rss.xml.get.ts

@@ -0,0 +1,13 @@
+import { createError, defineEventHandler, getRouterParam } from "h3";
+import { defaultLocale, isLocaleCode } from "../../../../i18n/locales";
+import { serveBlogFeed } from "../../../utils/blog-feed";
+
+// A param route keeps the router free of static locale segments; a static
+// /de/... node would shadow ginko-content's /:locale/llms.txt routes.
+export default defineEventHandler(async (event) => {
+  const locale = getRouterParam(event, "locale");
+  if (!locale || !isLocaleCode(locale) || locale === defaultLocale) {
+    throw createError({ statusCode: 404, statusMessage: "Page not found" });
+  }
+  return serveBlogFeed(event, locale);
+});

package/server/routes/blog/rss.xml.get.ts

@@ -0,0 +1,5 @@
+import { defineEventHandler } from "h3";
+import { defaultLocale } from "../../../i18n/locales";
+import { serveBlogFeed } from "../../utils/blog-feed";
+
+export default defineEventHandler((event) => serveBlogFeed(event, defaultLocale));

package/server/utils/blog-feed.ts

@@ -0,0 +1,49 @@
+import type { H3Event } from "h3";
+import { createError, setHeader } from "h3";
+import { many } from "@lupinum/ginko-content/server";
+import { useAppConfig, useRuntimeConfig } from "#imports";
+import { blog } from "../../i18n/messages/global/blog";
+import { locales, localizedPath, type LocaleCode } from "../../i18n/locales";
+import { routeSlugs } from "../../shared/route-slugs";
+import { getLocalizedSiteText } from "../../app/config/site.utils";
+import { buildRssFeed } from "./feed";
+
+export const MAX_FEED_POSTS = 50;
+
+export function blogFeedPath(locale: LocaleCode): string {
+  return `${localizedPath(locale, routeSlugs.blog[locale])}/rss.xml`;
+}
+
+export async function serveBlogFeed(event: H3Event, locale: LocaleCode) {
+  const contentRuntime = useRuntimeConfig(event).public.content as
+    | { collections?: Record<string, unknown> }
+    | undefined;
+  if (!contentRuntime?.collections?.blog) {
+    throw createError({ statusCode: 404, statusMessage: "Blog is not enabled" });
+  }
+
+  const site = useAppConfig().ginkoDocs.site;
+  const posts = await many(event, "blog", {
+    locale,
+    fallback: true,
+    populate: { author: "authors" },
+    sort: { date: "desc" },
+    limit: MAX_FEED_POSTS,
+  });
+
+  setHeader(event, "content-type", "application/rss+xml; charset=utf-8");
+  return buildRssFeed({
+    title: `${blog.title[locale]} - ${getLocalizedSiteText(site.name, locale)}`,
+    description: blog.description[locale],
+    siteUrl: site.url,
+    feedPath: blogFeedPath(locale),
+    language: locales.find((entry) => entry.code === locale)?.language ?? locale,
+    items: posts.map((post) => ({
+      title: post.title,
+      path: post.route.resolvedPath,
+      description: post.description,
+      date: post.date,
+      authorName: post.author?.name,
+    })),
+  });
+}

package/server/utils/feed.ts

@@ -0,0 +1,70 @@
+export interface RssFeedItem {
+  title: string;
+  /** Site-relative path of the post, e.g. "/blog/my-post". */
+  path: string;
+  description: string;
+  /** Authored publication date, YYYY-MM-DD. */
+  date: string;
+  authorName?: string;
+}
+
+export interface RssFeedInput {
+  title: string;
+  description: string;
+  /** Absolute site origin, e.g. "https://docs.example.com". */
+  siteUrl: string;
+  /** Site-relative path of the feed itself, e.g. "/blog/rss.xml". */
+  feedPath: string;
+  language: string;
+  items: RssFeedItem[];
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+function toRfc822(date: string): string {
+  return new Date(`${date}T00:00:00Z`).toUTCString();
+}
+
+export function buildRssFeed(feed: RssFeedInput): string {
+  const base = feed.siteUrl.replace(/\/$/, "");
+  const newestDate = feed.items
+    .map((item) => item.date)
+    .sort()
+    .at(-1);
+
+  const items = feed.items
+    .map((item) => {
+      const link = `${base}${item.path}`;
+      const author = item.authorName
+        ? `\n      <dc:creator>${escapeXml(item.authorName)}</dc:creator>`
+        : "";
+      return `    <item>
+      <title>${escapeXml(item.title)}</title>
+      <link>${escapeXml(link)}</link>
+      <guid>${escapeXml(link)}</guid>
+      <pubDate>${toRfc822(item.date)}</pubDate>
+      <description>${escapeXml(item.description)}</description>${author}
+    </item>`;
+    })
+    .join("\n");
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
+  <channel>
+    <title>${escapeXml(feed.title)}</title>
+    <link>${escapeXml(`${base}${feed.feedPath.replace(/rss\.xml$/, "")}`)}</link>
+    <atom:link href="${escapeXml(`${base}${feed.feedPath}`)}" rel="self" type="application/rss+xml"/>
+    <description>${escapeXml(feed.description)}</description>
+    <language>${escapeXml(feed.language)}</language>${newestDate ? `\n    <lastBuildDate>${toRfc822(newestDate)}</lastBuildDate>` : ""}
+${items}
+  </channel>
+</rss>
+`;
+}

package/server/utils/redirects.ts

@@ -0,0 +1,38 @@
+import type { H3Event } from "h3";
+import { many } from "@lupinum/ginko-content/server";
+import { useRuntimeConfig } from "#imports";
+import { localeCodes } from "../../i18n/locales";
+import { buildRedirectMap, type RedirectSourceDocument } from "./redirects.utils";
+
+async function queryRedirectDocuments(event: H3Event): Promise<RedirectSourceDocument[]> {
+  const contentRuntime = useRuntimeConfig(event).public.content as
+    | { collections?: Record<string, unknown> }
+    | undefined;
+  const collections = ["docs", ...(contentRuntime?.collections?.blog ? ["blog"] : [])];
+
+  const results = await Promise.all(
+    collections.flatMap((collection) =>
+      localeCodes.map((locale) =>
+        // fallback: false — an English page resolved into a German route would
+        // otherwise register its redirectFrom entries twice.
+        many(event, collection, { locale, fallback: false }),
+      ),
+    ),
+  );
+  return results.flat() as RedirectSourceDocument[];
+}
+
+let cachedMap: Promise<Map<string, string>> | undefined;
+
+export function loadRedirectMap(event: H3Event): Promise<Map<string, string>> {
+  if (import.meta.dev) {
+    return queryRedirectDocuments(event).then(buildRedirectMap);
+  }
+  cachedMap ??= queryRedirectDocuments(event)
+    .then(buildRedirectMap)
+    .catch((error) => {
+      cachedMap = undefined;
+      throw error;
+    });
+  return cachedMap;
+}

package/server/utils/redirects.utils.ts

@@ -0,0 +1,58 @@
+import { localeCodes, localizedPath } from "../../i18n/locales";
+import { routeSlugs } from "../../shared/route-slugs";
+
+export interface RedirectSourceDocument {
+  route: { resolvedPath: string };
+  redirectFrom?: string[];
+}
+
+export function normalizeRedirectPath(path: string): string {
+  const trimmed = path.split("?")[0] ?? path;
+  if (trimmed === "/") return "/";
+  return trimmed.replace(/\/+$/, "");
+}
+
+/** Routes the theme itself owns; a redirect must never shadow one of them. */
+export function themeStaticRoutes(): string[] {
+  return localeCodes.flatMap((locale) => [
+    localizedPath(locale, routeSlugs.home[locale]),
+    localizedPath(locale, routeSlugs.docs[locale]),
+    localizedPath(locale, routeSlugs.blog[locale]),
+  ]);
+}
+
+/**
+ * Builds old-path → live-path pairs from every document's `redirectFrom`.
+ * Conflicts throw so `failOnError` stops the build instead of shipping a
+ * redirect that shadows a live page.
+ */
+export function buildRedirectMap(documents: RedirectSourceDocument[]): Map<string, string> {
+  const livePaths = new Set(
+    documents.map((document) => normalizeRedirectPath(document.route.resolvedPath)),
+  );
+  const reserved = new Set(themeStaticRoutes().map(normalizeRedirectPath));
+  const map = new Map<string, string>();
+  const problems: string[] = [];
+
+  for (const document of documents) {
+    const target = normalizeRedirectPath(document.route.resolvedPath);
+    for (const source of document.redirectFrom ?? []) {
+      const from = normalizeRedirectPath(source);
+      if (livePaths.has(from)) {
+        problems.push(`"${from}" redirects to "${target}" but is also a live page`);
+      } else if (reserved.has(from)) {
+        problems.push(`"${from}" redirects to "${target}" but is a theme route`);
+      } else if (map.has(from) && map.get(from) !== target) {
+        problems.push(`"${from}" is claimed by both "${map.get(from)}" and "${target}"`);
+      } else {
+        map.set(from, target);
+      }
+    }
+  }
+
+  if (problems.length) {
+    throw new Error(`Invalid redirectFrom entries:\n${problems.map((p) => `- ${p}`).join("\n")}`);
+  }
+
+  return map;
+}