@lupinum/ginko-docs 0.2.3 → 0.2.5

package/README.md

@@ -8,14 +8,14 @@ Ginko Docs is a Nuxt layer for focused documentation sites. It combines Ginko Co
 - Nuxt `>=4.4.7 <5`
 - Vue `^3.5.35`
 - Vue Router `^5.1.0`
-- Ginko Content `>=0.3.2 <0.4.0`
+- Ginko Content `>=0.3.5 <0.4.0`
 
 ## Install
 
 Install the layer and its Ginko Content peer:
 
 ```bash
-pnpm add -D @lupinum/ginko-docs @lupinum/ginko-content@0.3.2
+pnpm add -D @lupinum/ginko-docs @lupinum/ginko-content@0.3.5
 ```
 
 Keep the public identity in one shared value:

package/app/app.config.ts

@@ -19,7 +19,7 @@ export default {
       docsSidebarSwitcher: "tabs",
       lupinumAttribution: true,
     },
-    nav: { links: "auto" },
+    nav: { links: "auto", socialIcons: false },
     banner: {
       enabled: false,
       id: "default",

package/app/app.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { getLocalizedSiteText } from "#ginko-docs/config/site.utils";
+import { computed } from "vue";
 import { useAppConfig, useHead, useI18n, useRoute, useSeoMeta } from "#imports";
 import { useLocalizedRouteSwitch } from "#ginko-docs/composables/useLocalizedRouteSwitch";
 import { useCanonicalUrl } from "#ginko-docs/composables/useCanonicalUrl";
@@ -16,6 +17,7 @@ const docsConfig = useAppConfig().ginkoDocs;
 const siteUrl = docsConfig.site.url;
 
 useSeoMeta({
+  ogSiteName: computed(() => getLocalizedSiteText(docsConfig.site.name, locale.value)),
   ogUrl: canonicalUrl,
   twitterCard: "summary_large_image",
 });

package/app/components/prose/ProseImg.vue

@@ -1,5 +1,10 @@
 <script setup lang="ts">
 import type { HTMLAttributes } from "vue";
+import { computed, resolveComponent } from "vue";
+import { Motion } from "motion-v";
+import { useI18n } from "#imports";
+import ImageZoomDialog from "#ginko-docs/components/content/ImageZoomDialog.vue";
+import { useGinkoDocsConfig } from "#ginko-docs/composables/useGinkoDocsConfig";
 import { cn } from "../../utils";
 
 const props = defineProps<{
@@ -10,18 +15,41 @@ const props = defineProps<{
   height?: string | number;
   class?: HTMLAttributes["class"];
 }>();
+
+const { t } = useI18n();
+const config = useGinkoDocsConfig();
+const zoomEnabled = computed(() => config.images?.zoom !== false);
+
+// External images skip NuxtImg; the layer ships no ipx domain allowlist.
+const isLocalAsset = computed(() => Boolean(props.src?.startsWith("/")));
+const imageComponent = computed(() => (isLocalAsset.value ? resolveComponent("NuxtImg") : "img"));
+const imageAttrs = computed(() => ({
+  src: props.src,
+  alt: props.alt ?? "",
+  title: props.title,
+  width: props.width,
+  height: props.height,
+  loading: "lazy" as const,
+  decoding: "async" as const,
+  class: cn("content-prose-image", props.class),
+  ...(isLocalAsset.value ? { sizes: "100vw md:704px" } : {}),
+}));
 </script>
 
 <template>
-  <img
-    v-if="src"
-    :src="src"
-    :alt="alt ?? ''"
-    :title="title"
-    :width="width"
-    :height="height"
-    loading="lazy"
-    decoding="async"
-    :class="cn('content-prose-image', props.class)"
-  />
+  <ImageZoomDialog v-if="src && zoomEnabled" :src="src" :alt="alt" :label="title">
+    <template #trigger="{ layoutId, transition }">
+      <!-- A button is phrasing content, so a bare markdown image stays valid inside its paragraph. -->
+      <button
+        type="button"
+        class="block max-w-full cursor-zoom-in rounded-[var(--radius)] focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none"
+        :aria-label="`${t('docs.zoomImage')}: ${alt ?? ''}`"
+      >
+        <Motion as-child :layout-id="layoutId" :transition="transition">
+          <component :is="imageComponent" v-bind="imageAttrs" />
+        </Motion>
+      </button>
+    </template>
+  </ImageZoomDialog>
+  <component :is="imageComponent" v-else-if="src" v-bind="imageAttrs" />
 </template>

package/app/components/site/SiteHeader.vue

@@ -26,9 +26,11 @@ import {
   normalizeDocsNavigationItem,
 } from "#ginko-docs/features/docs/docs-navigation";
 import ModeToggle from "#ginko-docs/components/site/ModeToggle.vue";
+import { useGinkoDocsConfig } from "#ginko-docs/composables/useGinkoDocsConfig";
 
 const { mainNav, socialLinks } = useSiteNavigation();
 const { openCommandCenter } = useCommandCenterState();
+const config = useGinkoDocsConfig();
 const { t } = useI18n();
 const route = useRoute();
 const isMobileMenuOpen = ref(false);
@@ -192,6 +194,10 @@ watch(
           </template>
         </ClientOnly>
 
+        <div v-if="config.nav.socialIcons" class="hidden md:block">
+          <SiteSocialLinks />
+        </div>
+
         <SiteLocaleSwitcher class="hidden md:flex" />
         <Sheet v-model:open="isMobileMenuOpen">
           <SheetTrigger as-child>
@@ -348,7 +354,12 @@ watch(
                     </template>
                   </ClientOnly>
                   <SiteLocaleSwitcher variant="pill" class="flex" @navigate="closeMenu" />
-                  <span v-if="socialLinks.length" class="ml-auto flex items-center gap-2">
+                  <SiteSocialLinks
+                    v-if="config.nav.socialIcons"
+                    class="ml-auto"
+                    @navigate="closeMenu"
+                  />
+                  <span v-else-if="socialLinks.length" class="ml-auto flex items-center gap-2">
                     <NuxtLink
                       v-for="link in socialLinks"
                       :key="link.href"

package/app/components/site/SiteLocaleSwitcher.vue

@@ -105,7 +105,7 @@ function trackLocaleNavigation(_entry: { code: string; current: boolean; to: unk
     <ClientOnly>
       <DropdownMenu>
         <DropdownMenuTrigger as-child>
-          <Button variant="outline" class="h-9 gap-1.5 px-2.5" :aria-label="t('nav.language')">
+          <Button variant="ghost" class="h-9 gap-1.5 px-2.5" :aria-label="t('nav.language')">
             <Icon
               v-if="currentLocale?.flagIcon"
               :name="currentLocale.flagIcon"
@@ -151,10 +151,8 @@ function trackLocaleNavigation(_entry: { code: string; current: boolean; to: unk
       </DropdownMenu>
 
       <template #fallback>
-        <span
-          class="inline-flex h-9 w-[4.25rem] rounded-md border border-border bg-background"
-          aria-hidden="true"
-        />
+        <!-- Reserves the trigger's box before hydration. -->
+        <span class="inline-flex h-9 w-[4.25rem] rounded-md" aria-hidden="true" />
       </template>
     </ClientOnly>
   </div>

package/app/components/site/SiteSocialLinks.vue

@@ -0,0 +1,31 @@
+<script setup lang="ts">
+import { Button } from "#ginko-docs/components/ui/button";
+import { useSiteNavigation } from "#ginko-docs/composables/useSiteNavigation";
+
+const { socialLinks } = useSiteNavigation();
+
+defineEmits<{ navigate: [] }>();
+</script>
+
+<template>
+  <div v-if="socialLinks.length" class="flex items-center">
+    <Button
+      v-for="link in socialLinks"
+      :key="link.href"
+      as-child
+      variant="ghost"
+      size="icon"
+      class="text-muted-foreground hover:text-foreground"
+    >
+      <NuxtLink
+        :to="link.href"
+        target="_blank"
+        rel="noopener noreferrer"
+        :aria-label="link.label"
+        @click="$emit('navigate')"
+      >
+        <Icon :name="link.icon ?? 'lucide:link'" class="size-[18px]" aria-hidden="true" />
+      </NuxtLink>
+    </Button>
+  </div>
+</template>

package/app/composables/site-navigation.utils.ts

@@ -1,4 +1,8 @@
-import type { GinkoDocsAppConfig, GinkoDocsLink } from "../../shared/types/app-config";
+import type {
+  GinkoDocsAppConfig,
+  GinkoDocsLink,
+  GinkoDocsSocialPlatform,
+} from "../../shared/types/app-config";
 import { getLocalizedSiteText } from "../config/site.utils";
 
 export interface NavItem {
@@ -7,6 +11,8 @@ export interface NavItem {
   external?: boolean;
   icon?: string;
   description?: string;
+  /** Set on social links so features can find a platform without matching its icon. */
+  platform?: GinkoDocsSocialPlatform;
 }
 
 export interface MainNavContext {
@@ -60,6 +66,39 @@ export function resolveMainNav(
   return items;
 }
 
+/**
+ * Brand names are not translated, so the labels are literals. The icons are
+ * bundled defaults — Lucide has no Discord mark, so chat is the closest generic
+ * stand-in and sites that ship the real one override `icon` per entry.
+ */
+const socialDefaults: Record<GinkoDocsSocialPlatform, { label: string; icon: string }> = {
+  github: { label: "GitHub", icon: "lucide:github" },
+  discord: { label: "Discord", icon: "lucide:message-circle" },
+  linkedin: { label: "LinkedIn", icon: "lucide:linkedin" },
+};
+
+export function resolveSocialLinks(social: GinkoDocsAppConfig["social"]): NavItem[] {
+  // Config order is render order, so a site can list Discord ahead of GitHub.
+  return Object.entries(social).flatMap<NavItem>(([key, entry]) => {
+    const platform = key as GinkoDocsSocialPlatform;
+    const defaults = socialDefaults[platform];
+    if (!defaults || !entry) return [];
+
+    const link = typeof entry === "string" ? { href: entry } : entry;
+    if (!link.href) return [];
+
+    return [
+      {
+        label: link.label ?? defaults.label,
+        href: link.href,
+        external: true,
+        icon: link.icon ?? defaults.icon,
+        platform,
+      },
+    ];
+  });
+}
+
 export interface BannerContext {
   locale: string;
   defaultText: string;

package/app/composables/useSiteNavigation.ts

@@ -3,7 +3,12 @@ import { useI18n, useRouter } from "#imports";
 import { useLocalizedPath } from "#ginko-docs/composables/useLocalizedPath";
 import { computed } from "vue";
 import { useGinkoDocsConfig } from "./useGinkoDocsConfig";
-import { resolveBanner, resolveMainNav, type NavItem } from "./site-navigation.utils";
+import {
+  resolveBanner,
+  resolveMainNav,
+  resolveSocialLinks,
+  type NavItem,
+} from "./site-navigation.utils";
 
 export const useSiteNavigation = () => {
   const config = useGinkoDocsConfig();
@@ -32,27 +37,7 @@ export const useSiteNavigation = () => {
     }),
   );
 
-  const socialLinks = computed<NavItem[]>(
-    () =>
-      [
-        config.social.github
-          ? {
-              label: t("nav.github"),
-              href: config.social.github,
-              external: true,
-              icon: "lucide:github",
-            }
-          : null,
-        config.social.linkedin
-          ? {
-              label: "LinkedIn",
-              href: config.social.linkedin,
-              external: true,
-              icon: "lucide:linkedin",
-            }
-          : null,
-      ].filter(Boolean) as NavItem[],
-  );
+  const socialLinks = computed<NavItem[]>(() => resolveSocialLinks(config.social));
 
   const mainNav = computed<NavItem[]>(() =>
     resolveMainNav(config.nav.links, {

package/app/features/docs/components/DocsPageContent.vue

@@ -1,5 +1,10 @@
 <script setup lang="ts">
-import { filterTocByDepth, flattenTocLinks, getMarkdownTocLinks } from "#ginko-docs/utils/content";
+import {
+  filterTocByDepth,
+  flattenTocLinks,
+  formatContentDate,
+  getMarkdownTocLinks,
+} from "#ginko-docs/utils/content";
 import ContentFeedback from "#ginko-docs/components/content/Feedback.vue";
 import DocsBreadcrumb from "./DocsBreadcrumb.vue";
 import DocsMobileToc from "./DocsMobileToc.vue";
@@ -182,6 +187,10 @@ function scrollToTop() {
           </div>
 
           <footer class="mt-12 border-t border-border pt-6">
+            <p v-if="page.updated" class="mb-4 text-sm text-muted-foreground">
+              {{ t("docs.lastUpdated") }}:
+              <time :datetime="page.updated">{{ formatContentDate(page.updated, locale) }}</time>
+            </p>
             <div class="flex flex-wrap items-center justify-between gap-x-6 gap-y-4">
               <ContentFeedback :label="t('feedback.label')" />
               <DocsContributeLinks

package/app/features/docs/components/DocsSidebar.vue

@@ -64,8 +64,14 @@ function setActiveSection(id: string) {
   if (path) void navigateTo(path);
 }
 
-const scrollViewportClass =
-  "size-full rounded-[inherit] p-4 pt-2 overscroll-contain [mask-image:linear-gradient(to_bottom,transparent,white_12px,white_calc(100%-12px),transparent)]";
+// The reduced top padding only applies under the section switcher; without it
+// the scroll mask would fade into the first group label.
+const scrollViewportClass = computed(() =>
+  cn(
+    "size-full rounded-[inherit] p-4 overscroll-contain [mask-image:linear-gradient(to_bottom,transparent,white_12px,white_calc(100%-12px),transparent)]",
+    switcherSections.value.length > 1 && "pt-2",
+  ),
+);
 
 // Deep links can land on an item far outside the visible band — center it
 // once on mount and on section switches.

package/app/features/search/useCommandCenter.ts

@@ -181,7 +181,7 @@ export async function useCommandCenter() {
   });
 
   const actionItems = computed<CommandCenterItem[]>(() => {
-    const github = socialLinks.value.find((item) => item.icon === "lucide:github");
+    const github = socialLinks.value.find((item) => item.platform === "github");
     return github
       ? [
           {
@@ -191,7 +191,7 @@ export async function useCommandCenter() {
             href: github.href,
             external: true,
             group: "actions" as const,
-            icon: "lucide:github",
+            icon: github.icon ?? "lucide:github",
             keywords: ["repo", "source", "code"],
           },
         ]

package/app/pages/blog/[slug].vue

@@ -80,7 +80,16 @@ useGinkoOgImage({
 });
 
 useHead(() => ({
-  link: [{ key: "canonical", rel: "canonical", href: canonicalUrl.value }],
+  link: [
+    { key: "canonical", rel: "canonical", href: canonicalUrl.value },
+    {
+      key: "rss",
+      rel: "alternate",
+      type: "application/rss+xml",
+      title: `${t("blog.title")} - ${siteName.value}`,
+      href: `${localizedPath("blog")}/rss.xml`,
+    },
+  ],
   meta: [{ property: "og:type", content: "article" }],
 }));
 

package/app/pages/blog/index.vue

@@ -6,6 +6,7 @@ import { getLocalizedSiteText } from "#ginko-docs/config/site.utils";
 import { computed } from "vue";
 import { definePageMeta, useAppConfig, useAsyncData, useHead, useI18n, useSeoMeta } from "#imports";
 import { useCanonicalUrl } from "#ginko-docs/composables/useCanonicalUrl";
+import { useLocalizedPath } from "#ginko-docs/composables/useLocalizedPath";
 
 const MAX_BLOG_POSTS = 50;
 
@@ -14,6 +15,7 @@ definePageMeta({ layout: "blog" });
 const { locale, t } = useI18n();
 const postsKey = computed(() => `blog-posts:${locale.value}`);
 const canonicalUrl = useCanonicalUrl();
+const localizedPath = useLocalizedPath();
 const config = useAppConfig().ginkoDocs;
 const siteName = computed(() => getLocalizedSiteText(config.site.name, locale.value));
 const fullTitle = computed(() => `${t("blog.pageTitle")} - ${siteName.value}`);
@@ -28,7 +30,16 @@ useSeoMeta({
 });
 
 useHead(() => ({
-  link: [{ key: "canonical", rel: "canonical", href: canonicalUrl.value }],
+  link: [
+    { key: "canonical", rel: "canonical", href: canonicalUrl.value },
+    {
+      key: "rss",
+      rel: "alternate",
+      type: "application/rss+xml",
+      title: fullTitle.value,
+      href: `${localizedPath("blog")}/rss.xml`,
+    },
+  ],
 }));
 
 const { data: queriedPosts, error } = await useAsyncData(

package/app/pages/index.vue

@@ -98,9 +98,13 @@ async function copyInstallCommand() {
   await copy(landing.value.install?.command ?? "");
 }
 
+const landingTitle = computed(() => localize(config.site.name));
+const landingDescription = computed(() => localize(config.site.description));
 useSeoMeta({
-  title: computed(() => localize(config.site.name)),
-  description: computed(() => localize(config.site.description)),
+  title: landingTitle,
+  description: landingDescription,
+  ogTitle: landingTitle,
+  ogDescription: landingDescription,
 });
 </script>
 

package/content.js

@@ -25,31 +25,52 @@ const routeSlugs = {
 //#region layer/content.ts
 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);
-const docsSchema = z.object({
-  title: z.string(),
-  description: z.string(),
-  icon: z.string().optional(),
-  badge: z.string().optional(),
-  updated: isoDate.optional(),
-  sidebar: z.enum(["section", "group"]).optional(),
-  navigation: z
-    .object({
-      title: z.string().optional(),
-      icon: z.string().optional(),
-      badge: z.string().optional(),
-      sidebar: z.enum(["section", "group"]).optional(),
-    })
-    .optional(),
-});
-const blogSchema = z.object({
-  title: z.string(),
-  description: z.string(),
-  badge: z.string().optional(),
-  date: isoDate,
-  readingTime: nonEmptyString,
-  author: reference("authors"),
-  image: z.string().optional(),
-});
+/** 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 = (data, lastmod) =>
+  lastmod
+    ? {
+        ...data,
+        sitemap: { lastmod: `${lastmod}T00:00:00.000Z` },
+      }
+    : data;
+const docsSchemaWithLastmod = z
+  .object({
+    title: z.string(),
+    description: z.string(),
+    icon: z.string().optional(),
+    badge: z.string().optional(),
+    updated: isoDate.optional(),
+    redirectFrom,
+    sidebar: z.enum(["section", "group"]).optional(),
+    navigation: z
+      .object({
+        title: z.string().optional(),
+        icon: z.string().optional(),
+        badge: z.string().optional(),
+        sidebar: z.enum(["section", "group"]).optional(),
+      })
+      .optional(),
+  })
+  .transform((data) => withSitemapLastmod(data, data.updated));
+const blogSchemaWithLastmod = z
+  .object({
+    title: z.string(),
+    description: z.string(),
+    badge: z.string().optional(),
+    date: isoDate,
+    readingTime: nonEmptyString,
+    author: reference("authors"),
+    image: z.string().optional(),
+    redirectFrom,
+  })
+  .transform((data) => withSitemapLastmod(data, data.date));
 const authorsSchema = z.object({
   slug: z.string(),
   name: z.string(),
@@ -95,7 +116,7 @@ function defineGinkoDocsConfig(options) {
       markdown: true,
     },
     strict: true,
-    schema: docsSchema,
+    schema: docsSchemaWithLastmod,
   });
   const blog = defineCollection({
     type: "page",
@@ -107,7 +128,7 @@ function defineGinkoDocsConfig(options) {
       markdown: true,
     },
     strict: true,
-    schema: blogSchema,
+    schema: blogSchemaWithLastmod,
   });
   const authors = defineCollection({
     type: "data",

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.2.5",
   },
   components: {
     dirs: [
@@ -57,6 +59,7 @@ export default defineNuxtConfig({
           "SiteLocaleSwitcher.vue",
           "SiteLogoMark.vue",
           "SiteSkipLink.vue",
+          "SiteSocialLinks.vue",
         ],
       },
       {
@@ -115,6 +118,9 @@ 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,
     },
@@ -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.2.5",
   "description": "A Nuxt documentation layer powered by Ginko Content.",
   "keywords": [
     "content",
@@ -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.7",
+    "reka-ui": "^2.10.3",
+    "satori": "^0.29.0",
+    "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.3.5 <0.4.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;
+}

package/shared/types/app-config.ts

@@ -34,6 +34,15 @@ export interface GinkoDocsLink {
   description?: GinkoDocsLocalizedText;
 }
 
+export type GinkoDocsSocialPlatform = "github" | "discord" | "linkedin";
+
+/**
+ * A URL uses the platform's built-in label and icon. Pass an object to override
+ * either — `icon` accepts any Iconify name the consuming app has registered, so
+ * sites that ship brand marks are not limited to the layer's bundled icons.
+ */
+export type GinkoDocsSocialEntry = string | { href: string; label?: string; icon?: string };
+
 export interface GinkoDocsHeroCodeTab {
   label: GinkoDocsLocalizedText;
   /** Iconify icon shown in the tab. */
@@ -77,6 +86,8 @@ export interface GinkoDocsAppConfig {
   nav: {
     /** "auto" derives Docs (+ Blog when blog routes exist); an array overrides entirely. */
     links: "auto" | GinkoDocsLink[];
+    /** Render configured social links as icon buttons in the header instead of labelled rows. */
+    socialIcons: boolean;
   };
   banner: {
     enabled: boolean;
@@ -96,10 +107,7 @@ export interface GinkoDocsAppConfig {
       extensions?: GinkoDocsPlausibleExtension[];
     };
   };
-  social: {
-    github?: string;
-    linkedin?: string;
-  };
+  social: Partial<Record<GinkoDocsSocialPlatform, GinkoDocsSocialEntry>>;
   feedback: {
     enabled: boolean;
   };