@lupinum/ginko-docs 0.3.0 → 0.4.0-rc.10

package/modules/feature-routing.ts

@@ -1,5 +1,6 @@
 import { defineNuxtModule, installModule } from "@nuxt/kit";
 import type {} from "@lupinum/ginko-content";
+import type { LocaleCode } from "../i18n/locales";
 import { defaultLocale, localeCodes, locales, localizedPath } from "../i18n/locales";
 import { routeSlugs } from "../shared/route-slugs";
 
@@ -7,9 +8,39 @@ interface PageRoute {
   path: string;
 }
 
-export const blogFeedRoutes = localeCodes.map(
-  (locale) => `${localizedPath(locale, routeSlugs.blog[locale])}/rss.xml`,
-);
+function configuredLocaleCodes(configuredLocales: unknown) {
+  if (!Array.isArray(configuredLocales)) return new Set<string>();
+  return new Set(
+    configuredLocales.flatMap((locale) => {
+      if (typeof locale === "string") return [locale];
+      return locale && typeof locale === "object" && typeof locale.code === "string"
+        ? [locale.code]
+        : [];
+    }),
+  );
+}
+
+function removeInactivePageLocales(
+  pages: Record<string, unknown> | undefined,
+  activeLocales: ReadonlySet<string>,
+) {
+  if (!pages || activeLocales.size === 0) return;
+
+  for (const routeMap of Object.values(pages)) {
+    if (!routeMap || typeof routeMap !== "object" || Array.isArray(routeMap)) continue;
+    for (const locale of Object.keys(routeMap)) {
+      if (!activeLocales.has(locale)) delete (routeMap as Record<string, unknown>)[locale];
+    }
+  }
+}
+
+export const blogFeedRoutes = (
+  primaryLocale: LocaleCode = defaultLocale,
+  activeLocales: ReadonlySet<string> = new Set(localeCodes),
+) =>
+  localeCodes
+    .filter((locale) => activeLocales.has(locale))
+    .map((locale) => `${localizedPath(locale, routeSlugs.blog[locale], primaryLocale)}/rss.xml`);
 
 export function removeBlogPages(pages: PageRoute[], blogEnabled: boolean) {
   if (blogEnabled) return;
@@ -25,25 +56,19 @@ export function removeBlogPages(pages: PageRoute[], blogEnabled: boolean) {
 export default defineNuxtModule({
   meta: { name: "ginko-docs-feature-routing" },
   async setup(_options, nuxt) {
-    const fallback = locales.find((locale) => locale.code === defaultLocale);
-    if (!fallback) throw new Error(`Missing locale definition for ${defaultLocale}.`);
-    const configuredLocales = nuxt.options.i18n?.locales;
-    if (!Array.isArray(configuredLocales) || configuredLocales.length === 0) {
-      nuxt.options.i18n = {
-        ...nuxt.options.i18n,
-        locales: [{ code: fallback.code, language: fallback.language, name: fallback.name }],
-      };
-    } else if (configuredLocales.length > 1) {
-      const fallbackIndex = configuredLocales.findIndex(
-        (locale) =>
-          typeof locale === "object" &&
-          locale !== null &&
-          locale.code === fallback.code &&
-          locale.language === fallback.language &&
-          locale.name === fallback.name,
-      );
-      if (fallbackIndex >= 0) configuredLocales.splice(fallbackIndex, 1);
+    const ginkoDocs = nuxt.options.ginkoDocs;
+    const primaryLocale =
+      ginkoDocs && typeof ginkoDocs === "object"
+        ? (ginkoDocs.primaryLocale ?? defaultLocale)
+        : defaultLocale;
+    if (!locales.some((locale) => locale.code === primaryLocale)) {
+      throw new Error(`Missing locale definition for ${primaryLocale}.`);
     }
+    const activeLocales = configuredLocaleCodes(nuxt.options.i18n?.locales);
+    removeInactivePageLocales(
+      nuxt.options.i18n?.pages as Record<string, unknown> | undefined,
+      activeLocales,
+    );
     await installModule("@nuxtjs/i18n");
 
     let blogEnabled = false;
@@ -62,7 +87,7 @@ export default defineNuxtModule({
       if (!blogEnabled) return;
       nitroConfig.prerender ??= {};
       nitroConfig.prerender.routes ??= [];
-      nitroConfig.prerender.routes.push(...blogFeedRoutes);
+      nitroConfig.prerender.routes.push(...blogFeedRoutes(primaryLocale, activeLocales));
     });
   },
 });

package/modules/syntax-highlighting.ts

@@ -5,6 +5,8 @@ import type {
   GinkoDocsSyntaxHighlightingConfig,
   GinkoDocsNuxtConfig,
 } from "../shared/types/nuxt-config";
+import type { LocaleCode } from "../i18n/locales";
+import { defaultLocale } from "../i18n/locales";
 
 export const DEFAULT_SYNTAX_THEMES = {
   light: "light-plus",
@@ -77,9 +79,11 @@ export async function patchShikiThemes(
 export function mergeSyntaxRuntimeConfig(
   current: Record<string, unknown> | undefined,
   themes: GinkoDocsSyntaxHighlightingConfig["themes"],
+  primaryLocale: LocaleCode = defaultLocale,
 ) {
   return {
     ...current,
+    primaryLocale,
     syntaxHighlighting: {
       themes: {
         light: themes.light,
@@ -100,6 +104,7 @@ export default defineNuxtModule<GinkoDocsNuxtConfig>({
     nuxt.options.runtimeConfig.public.ginkoDocs = mergeSyntaxRuntimeConfig(
       nuxt.options.runtimeConfig.public.ginkoDocs,
       themes,
+      options.primaryLocale,
     );
 
     if (!options.syntaxHighlighting) return;

package/nuxt.config.ts

@@ -7,9 +7,10 @@ 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 { defaultLocale, localeCodes, locales, localizedPath } from "./i18n/locales";
+import { localeCodes, localizedPath } from "./i18n/locales";
 import { routeSlugs } from "./shared/route-slugs";
 import { layerIconCollections, layerIconNames } from "./icon-bundle";
+import packageMetadata from "./package.json" with { type: "json" };
 
 const root = dirname(fileURLToPath(import.meta.url));
 const app = join(root, "app");
@@ -56,7 +57,7 @@ export default defineNuxtConfig({
   },
   mcp: {
     name: "Ginko Docs",
-    version: "0.3.0",
+    version: packageMetadata.version,
   },
   components: {
     dirs: [
@@ -129,9 +130,6 @@ export default defineNuxtConfig({
     customRoutes: "config",
     defaultLocale: "en",
     detectBrowserLanguage: false,
-    locales: locales
-      .filter((locale) => locale.code === defaultLocale)
-      .map(({ code, language, name }) => ({ code, language, name })),
     pages: i18nPages,
     strategy: "prefix_except_default",
     vueI18n: join(root, "i18n/i18n.config.ts"),
@@ -163,13 +161,15 @@ export default defineNuxtConfig({
     },
     search: { engine: "minisearch" },
     sitemap: true,
-    agent: { routes: true, linkHeaders: true, markdownNegotiation: true, prerender: true },
+    agent: { routes: true, linkHeaders: true, delivery: "static" },
   },
   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])),
+    exclude: localeCodes.flatMap((primaryLocale) =>
+      localeCodes.map((locale) => localizedPath(locale, routeSlugs.docs[locale], primaryLocale)),
+    ),
   },
   app: {
     head: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lupinum/ginko-docs",
-  "version": "0.3.0",
+  "version": "0.4.0-rc.10",
   "description": "A Nuxt documentation layer powered by Ginko Content.",
   "keywords": [
     "content",
@@ -20,6 +20,9 @@
     "url": "git+https://github.com/lupinum-dev/ginko-docs.git",
     "directory": "layer"
   },
+  "bin": {
+    "ginko-docs-favicons": "./runtime/generate-favicons.mjs"
+  },
   "files": [
     "app",
     "i18n",
@@ -74,21 +77,23 @@
     "@vueuse/core": "^14.4.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
+    "h3": "1.15.11",
     "motion-v": "^2.3.0",
     "nitropack": "^2.13.4",
     "nuxt-og-image": "^6.7.8",
     "reka-ui": "^2.10.3",
     "satori": "^0.19.3",
+    "sharp": "^0.35.4",
     "shiki": "^4.4.3",
     "tailwind-merge": "^3.6.0",
     "tailwindcss": "^4.3.3",
     "tw-animate-css": "^1.4.0",
-    "zod": "^4.4.3"
+    "zod": "4.4.3"
   },
   "peerDependencies": {
-    "@lupinum/ginko-content": ">=0.4.0-rc.2 <0.5.0",
+    "@lupinum/ginko-content": ">=1.0.0-beta.7 <2.0.0",
     "nuxt": ">=4.5.1 <5",
-    "vue": "^3.5.35",
+    "vue": "^3.5.40",
     "vue-router": "^5.1.0"
   },
   "engines": {

package/runtime/generate-favicons.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { extname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import sharp from "sharp";
+
+const ICO_SIZES = [16, 32, 48];
+
+function createIco(images) {
+  const headerSize = 6;
+  const entrySize = 16;
+  const directory = Buffer.alloc(headerSize + entrySize * images.length);
+
+  directory.writeUInt16LE(0, 0);
+  directory.writeUInt16LE(1, 2);
+  directory.writeUInt16LE(images.length, 4);
+
+  let imageOffset = directory.length;
+  images.forEach(({ size, data }, index) => {
+    const entryOffset = headerSize + entrySize * index;
+    directory.writeUInt8(size === 256 ? 0 : size, entryOffset);
+    directory.writeUInt8(size === 256 ? 0 : size, entryOffset + 1);
+    directory.writeUInt8(0, entryOffset + 2);
+    directory.writeUInt8(0, entryOffset + 3);
+    directory.writeUInt16LE(1, entryOffset + 4);
+    directory.writeUInt16LE(32, entryOffset + 6);
+    directory.writeUInt32LE(data.length, entryOffset + 8);
+    directory.writeUInt32LE(imageOffset, entryOffset + 12);
+    imageOffset += data.length;
+  });
+
+  return Buffer.concat([directory, ...images.map(({ data }) => data)]);
+}
+
+async function renderSquare(source, size) {
+  return sharp(source, { density: 512 }).resize(size, size, { fit: "contain" }).png().toBuffer();
+}
+
+function embeddedSvg(png) {
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img">
+  <image width="512" height="512" href="data:image/png;base64,${png.toString("base64")}" />
+</svg>
+`;
+}
+
+export async function generateFavicons({ source, outputDirectory }) {
+  const sourcePath = resolve(source);
+  const outputPath = resolve(outputDirectory);
+  const sourceBuffer = await readFile(sourcePath);
+  const metadata = await sharp(sourceBuffer, { density: 512 }).metadata();
+
+  if (!metadata.width || !metadata.height) {
+    throw new Error(`Could not read icon dimensions from ${sourcePath}`);
+  }
+  if (metadata.width !== metadata.height) {
+    throw new Error(
+      `The favicon source must be square. Received ${metadata.width}x${metadata.height}.`,
+    );
+  }
+
+  const [png96, appleTouchIcon, ...icoPngs] = await Promise.all([
+    renderSquare(sourceBuffer, 96),
+    renderSquare(sourceBuffer, 180),
+    ...ICO_SIZES.map(async (size) => ({ size, data: await renderSquare(sourceBuffer, size) })),
+  ]);
+
+  const svg =
+    extname(sourcePath).toLowerCase() === ".svg"
+      ? sourceBuffer
+      : Buffer.from(embeddedSvg(await renderSquare(sourceBuffer, 512)));
+
+  await mkdir(outputPath, { recursive: true });
+  await Promise.all([
+    writeFile(join(outputPath, "favicon.svg"), svg),
+    writeFile(join(outputPath, "favicon-96x96.png"), png96),
+    writeFile(join(outputPath, "apple-touch-icon.png"), appleTouchIcon),
+    writeFile(join(outputPath, "favicon.ico"), createIco(icoPngs)),
+  ]);
+
+  return ["favicon.svg", "favicon-96x96.png", "apple-touch-icon.png", "favicon.ico"];
+}
+
+function parseArguments(arguments_) {
+  const options = {
+    source: "public/favicon.svg",
+    outputDirectory: "public",
+  };
+
+  for (let index = 0; index < arguments_.length; index += 1) {
+    const argument = arguments_[index];
+    if (argument === "--source") options.source = arguments_[++index];
+    else if (argument === "--out") options.outputDirectory = arguments_[++index];
+    else if (argument === "--help" || argument === "-h") return undefined;
+    else throw new Error(`Unknown argument: ${argument}`);
+  }
+
+  if (!options.source || !options.outputDirectory) {
+    throw new Error("Both --source and --out require a path.");
+  }
+  return options;
+}
+
+async function main() {
+  const options = parseArguments(process.argv.slice(2));
+  if (!options) {
+    console.log(`Usage: ginko-docs-favicons [--source <path>] [--out <directory>]
+
+Defaults:
+  --source public/favicon.svg
+  --out public`);
+    return;
+  }
+
+  const files = await generateFavicons(options);
+  console.log(`Generated ${files.join(", ")} in ${resolve(options.outputDirectory)}`);
+}
+
+if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+  });
+}

package/server/plugins/sitemap-policy.ts

@@ -0,0 +1,19 @@
+import { defineNitroPlugin } from "nitropack/runtime/plugin";
+import { filterSitemapEntries } from "../utils/sitemap";
+import { defaultLocale, isLocaleCode } from "../../i18n/locales";
+
+export default defineNitroPlugin((nitro) => {
+  nitro.hooks.hook("sitemap:resolved", (context) => {
+    const runtimeConfig = useRuntimeConfig(context.event);
+    const content = runtimeConfig.content;
+    const configuredPrimaryLocale = runtimeConfig.public.ginkoDocs?.primaryLocale;
+    context.urls = filterSitemapEntries(context.urls, {
+      locales: content.locales,
+      blogEnabled: Boolean(content.collections.blog),
+      primaryLocale:
+        typeof configuredPrimaryLocale === "string" && isLocaleCode(configuredPrimaryLocale)
+          ? configuredPrimaryLocale
+          : defaultLocale,
+    });
+  });
+});

package/server/routes/.well-known/ai-catalog.json.get.ts

@@ -0,0 +1,10 @@
+import { useAppConfig } from "#imports";
+import { createGinkoDocsAiCatalog } from "../../utils/mcp-server-card";
+
+export default defineEventHandler((event) => {
+  event.node.res.setHeader("access-control-allow-origin", "*");
+  event.node.res.setHeader("cache-control", "public, max-age=3600");
+  event.node.res.setHeader("content-type", "application/ai-catalog+json; charset=utf-8");
+
+  return createGinkoDocsAiCatalog(useAppConfig().ginkoDocs.site.url);
+});

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

@@ -6,7 +6,12 @@ import { serveBlogFeed } from "../../../utils/blog-feed";
 // /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) {
+  const configuredPrimaryLocale = useRuntimeConfig(event).public.ginkoDocs?.primaryLocale;
+  const primaryLocale =
+    typeof configuredPrimaryLocale === "string" && isLocaleCode(configuredPrimaryLocale)
+      ? configuredPrimaryLocale
+      : defaultLocale;
+  if (!locale || !isLocaleCode(locale) || locale === primaryLocale) {
     throw createError({ statusCode: 404, statusMessage: "Page not found" });
   }
   return serveBlogFeed(event, locale);

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

@@ -1,5 +1,13 @@
 import { defineEventHandler } from "h3";
-import { defaultLocale } from "../../../i18n/locales";
+import { defaultLocale, isLocaleCode } from "../../../i18n/locales";
 import { serveBlogFeed } from "../../utils/blog-feed";
 
-export default defineEventHandler((event) => serveBlogFeed(event, defaultLocale));
+export default defineEventHandler((event) => {
+  const configuredPrimaryLocale = useRuntimeConfig(event).public.ginkoDocs?.primaryLocale;
+  return serveBlogFeed(
+    event,
+    typeof configuredPrimaryLocale === "string" && isLocaleCode(configuredPrimaryLocale)
+      ? configuredPrimaryLocale
+      : defaultLocale,
+  );
+});

package/server/routes/mcp/server-card.get.ts

@@ -0,0 +1,14 @@
+import { useAppConfig } from "#imports";
+import packageMetadata from "../../../package.json" with { type: "json" };
+import { createGinkoDocsServerCard } from "../../utils/mcp-server-card";
+
+export default defineEventHandler((event) => {
+  event.node.res.setHeader("access-control-allow-origin", "*");
+  event.node.res.setHeader("cache-control", "public, max-age=3600");
+  event.node.res.setHeader("content-type", "application/mcp-server-card+json; charset=utf-8");
+
+  return createGinkoDocsServerCard({
+    origin: useAppConfig().ginkoDocs.site.url,
+    version: packageMetadata.version,
+  });
+});

package/server/utils/blog-feed.ts

@@ -3,21 +3,34 @@ 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 {
+  defaultLocale,
+  isLocaleCode,
+  locales,
+  localizedPath,
+  type LocaleCode,
+} from "../../i18n/locales";
 import { routeSlugs } from "../../shared/route-slugs";
 import { getLocalizedSiteText } from "../../app/config/site.utils";
 import { createGinkoDocsCollections } from "../../content-collections";
 import { buildRssFeed } from "./feed";
 
 export const MAX_FEED_POSTS = 50;
-const { blog: blogCollection, authors: authorsCollection } = createGinkoDocsCollections(true);
+const { blog: blogCollection, authors: authorsCollection } = createGinkoDocsCollections([
+  "en",
+  "de",
+]);
 
-export function blogFeedPath(locale: LocaleCode): string {
-  return `${localizedPath(locale, routeSlugs.blog[locale])}/rss.xml`;
+export function blogFeedPath(
+  locale: LocaleCode,
+  primaryLocale: LocaleCode = defaultLocale,
+): string {
+  return `${localizedPath(locale, routeSlugs.blog[locale], primaryLocale)}/rss.xml`;
 }
 
 export async function serveBlogFeed(event: H3Event, locale: LocaleCode) {
-  const contentRuntime = useRuntimeConfig(event).public.content as
+  const publicRuntime = useRuntimeConfig(event).public;
+  const contentRuntime = publicRuntime.content as
     | { collections?: Record<string, unknown> }
     | undefined;
   if (!contentRuntime?.collections?.blog) {
@@ -25,6 +38,11 @@ export async function serveBlogFeed(event: H3Event, locale: LocaleCode) {
   }
 
   const site = useAppConfig().ginkoDocs.site;
+  const configuredPrimaryLocale = publicRuntime.ginkoDocs?.primaryLocale;
+  const primaryLocale =
+    typeof configuredPrimaryLocale === "string" && isLocaleCode(configuredPrimaryLocale)
+      ? configuredPrimaryLocale
+      : defaultLocale;
   const posts = await many(event, blogCollection, {
     locale,
     fallback: true,
@@ -38,7 +56,7 @@ export async function serveBlogFeed(event: H3Event, locale: LocaleCode) {
     title: `${blog.title[locale]} - ${getLocalizedSiteText(site.name, locale)}`,
     description: blog.description[locale],
     siteUrl: site.url,
-    feedPath: blogFeedPath(locale),
+    feedPath: blogFeedPath(locale, primaryLocale),
     language: locales.find((entry) => entry.code === locale)?.language ?? locale,
     items: posts.map((post) => ({
       title: post.title,

package/server/utils/mcp-server-card.ts

@@ -0,0 +1,45 @@
+export interface GinkoDocsServerCardOptions {
+  origin: string;
+  version: string;
+}
+
+export function createGinkoDocsServerCard({ origin, version }: GinkoDocsServerCardOptions) {
+  const baseUrl = new URL(origin);
+
+  return {
+    $schema: "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
+    name: "dev.lupinum/ginko-docs",
+    title: "Ginko Docs",
+    version,
+    description: "Read published Ginko Docs pages through its public MCP tools.",
+    websiteUrl: new URL("/docs/features/agent-readable-output", baseUrl).toString(),
+    repository: {
+      source: "github",
+      url: "https://github.com/lupinum-dev/ginko-docs",
+    },
+    remotes: [
+      {
+        type: "streamable-http",
+        url: new URL("/mcp", baseUrl).toString(),
+        supportedProtocolVersions: ["2025-11-25"],
+      },
+    ],
+  } as const;
+}
+
+export function createGinkoDocsAiCatalog(origin: string) {
+  const baseUrl = new URL(origin);
+
+  return {
+    specVersion: "1.0",
+    entries: [
+      {
+        identifier: "urn:air:ginko-docs.lupinum.com:mcp:ginko-docs",
+        displayName: "Ginko Docs MCP Server",
+        type: "application/mcp-server-card+json",
+        description: "Read the public Ginko Docs documentation through MCP.",
+        url: new URL("/mcp/server-card", baseUrl).toString(),
+      },
+    ],
+  } as const;
+}

package/server/utils/redirects.ts

@@ -1,7 +1,7 @@
 import type { H3Event } from "h3";
 import { many } from "@lupinum/ginko-content/server";
 import { useRuntimeConfig } from "#imports";
-import { localeCodes } from "../../i18n/locales";
+import { defaultLocale, isLocaleCode, localeCodes } from "../../i18n/locales";
 import { buildRedirectMap, type RedirectSourceDocument } from "./redirects.utils";
 
 async function queryRedirectDocuments(event: H3Event): Promise<RedirectSourceDocument[]> {
@@ -25,11 +25,18 @@ async function queryRedirectDocuments(event: H3Event): Promise<RedirectSourceDoc
 let cachedMap: Promise<Map<string, string>> | undefined;
 
 export function loadRedirectMap(event: H3Event): Promise<Map<string, string>> {
+  const configuredPrimaryLocale = useRuntimeConfig(event).public.ginkoDocs?.primaryLocale;
+  const primaryLocale =
+    typeof configuredPrimaryLocale === "string" && isLocaleCode(configuredPrimaryLocale)
+      ? configuredPrimaryLocale
+      : defaultLocale;
   if (import.meta.dev) {
-    return queryRedirectDocuments(event).then(buildRedirectMap);
+    return queryRedirectDocuments(event).then((documents) =>
+      buildRedirectMap(documents, primaryLocale),
+    );
   }
   cachedMap ??= queryRedirectDocuments(event)
-    .then(buildRedirectMap)
+    .then((documents) => buildRedirectMap(documents, primaryLocale))
     .catch((error) => {
       cachedMap = undefined;
       throw error;

package/server/utils/redirects.utils.ts

@@ -1,4 +1,4 @@
-import { localeCodes, localizedPath } from "../../i18n/locales";
+import { defaultLocale, localeCodes, localizedPath, type LocaleCode } from "../../i18n/locales";
 import { routeSlugs } from "../../shared/route-slugs";
 
 export interface RedirectSourceDocument {
@@ -13,11 +13,11 @@ export function normalizeRedirectPath(path: string): string {
 }
 
 /** Routes the theme itself owns; a redirect must never shadow one of them. */
-export function themeStaticRoutes(): string[] {
+export function themeStaticRoutes(primaryLocale: LocaleCode = defaultLocale): string[] {
   return localeCodes.flatMap((locale) => [
-    localizedPath(locale, routeSlugs.home[locale]),
-    localizedPath(locale, routeSlugs.docs[locale]),
-    localizedPath(locale, routeSlugs.blog[locale]),
+    localizedPath(locale, routeSlugs.home[locale], primaryLocale),
+    localizedPath(locale, routeSlugs.docs[locale], primaryLocale),
+    localizedPath(locale, routeSlugs.blog[locale], primaryLocale),
   ]);
 }
 
@@ -26,11 +26,14 @@ export function themeStaticRoutes(): string[] {
  * 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> {
+export function buildRedirectMap(
+  documents: RedirectSourceDocument[],
+  primaryLocale: LocaleCode = defaultLocale,
+): Map<string, string> {
   const livePaths = new Set(
     documents.map((document) => normalizeRedirectPath(document.route.resolvedPath)),
   );
-  const reserved = new Set(themeStaticRoutes().map(normalizeRedirectPath));
+  const reserved = new Set(themeStaticRoutes(primaryLocale).map(normalizeRedirectPath));
   const map = new Map<string, string>();
   const problems: string[] = [];
 

package/server/utils/sitemap.ts

@@ -0,0 +1,50 @@
+import { defaultLocale, localeCodes, localizedPath, type LocaleCode } from "../../i18n/locales";
+import { routeSlugs } from "../../shared/route-slugs";
+
+interface SitemapAlternative {
+  href: string;
+}
+
+export interface SitemapEntry {
+  loc: string;
+  alternatives?: SitemapAlternative[];
+}
+
+interface SitemapContentPolicy {
+  locales: readonly string[];
+  blogEnabled: boolean;
+  primaryLocale?: LocaleCode;
+}
+
+const pathname = (url: string) => new URL(url, "https://ginko.invalid").pathname;
+
+export function filterSitemapEntries<Entry extends SitemapEntry>(
+  entries: Entry[],
+  policy: SitemapContentPolicy,
+): Entry[] {
+  const requestedPrimaryLocale = policy.primaryLocale ?? defaultLocale;
+  const primaryLocale = policy.locales.includes(requestedPrimaryLocale)
+    ? requestedPrimaryLocale
+    : (localeCodes.find((locale) => policy.locales.includes(locale)) ?? defaultLocale);
+  const disabledLocaleRoots = localeCodes
+    .filter((locale) => !policy.locales.includes(locale))
+    .map((locale) => (locale === primaryLocale ? "/" : `/${locale}`));
+  const disabledBlogRoots = policy.blogEnabled
+    ? []
+    : localeCodes.map((locale) => localizedPath(locale, routeSlugs.blog[locale], primaryLocale));
+  const excludedRoots = [...disabledLocaleRoots, ...disabledBlogRoots];
+  const isExcluded = (url: string) => {
+    const path = pathname(url);
+    return excludedRoots.some((root) => path === root || path.startsWith(`${root}/`));
+  };
+
+  return entries
+    .filter((entry) => !isExcluded(entry.loc))
+    .map((entry) => {
+      if (!entry.alternatives) return entry;
+      return {
+        ...entry,
+        alternatives: entry.alternatives.filter((alternative) => !isExcluded(alternative.href)),
+      };
+    });
+}

package/shared/theme-presets.ts

@@ -0,0 +1,3 @@
+export const GINKO_DOCS_THEME_PRESETS = ["default", "nuxt"] as const;
+
+export type GinkoDocsThemePreset = (typeof GINKO_DOCS_THEME_PRESETS)[number];