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

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.4.0-rc.1 <0.5.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@0.3.0-rc.1 @lupinum/ginko-content@0.4.0-rc.1
 ```
 
 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/content/Feedback.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { Button } from "#ginko-docs/components/ui/button";
-import { computed, ref } from "vue";
-import { useI18n, useRoute } from "#imports";
+import { computed, ref, watch } from "vue";
+import { useI18n, useRouter } from "#imports";
 import { useGinkoAnalytics } from "#ginko-docs/composables/useGinkoAnalytics";
 import { useGinkoDocsConfig } from "#ginko-docs/composables/useGinkoDocsConfig";
 import { buildRepoIssueUrl } from "#ginko-docs/utils/repository";
@@ -15,7 +15,7 @@ withDefaults(
   },
 );
 const { t, locale } = useI18n();
-const route = useRoute();
+const router = useRouter();
 
 const config = useGinkoDocsConfig();
 const analytics = useGinkoAnalytics();
@@ -24,20 +24,24 @@ const enabled = config.feedback.enabled && analytics.enabled;
 type Sentiment = "positive" | "negative";
 
 const sentiment = ref<Sentiment | null>(null);
+const routePath = computed(() => router.currentRoute.value.path);
+watch(routePath, () => {
+  sentiment.value = null;
+});
 
 const issueUrl = computed(() => {
   const repository = config.repository;
   if (!repository) return null;
   return buildRepoIssueUrl(repository, {
-    title: t("feedback.issueTitle", { path: route.path }),
-    body: t("docs.issueBody", { path: route.path }),
+    title: t("feedback.issueTitle", { path: routePath.value }),
+    body: t("docs.issueBody", { path: routePath.value }),
   });
 });
 
 function selectSentiment(s: Sentiment) {
   if (sentiment.value !== null) return;
   analytics.track("docs-feedback", {
-    path: route.path,
+    path: routePath.value,
     helpful: s === "positive" ? "yes" : "no",
     locale: locale.value,
   });

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/useGinkoAnalytics.ts

@@ -10,28 +10,32 @@ export interface GinkoAnalytics {
 
 /**
  * Plausible analytics via the Nuxt Scripts registry script. Fully disabled
- * unless `ginkoDocs.analytics.plausible.domain` is configured — without a
- * domain nothing loads and `track()` is a no-op, so callers never guard.
+ * unless `ginkoDocs.analytics.plausible.scriptId` is configured. Without an
+ * ID, no script loads and `track()` is a no-op, so callers never guard.
  */
 export function useGinkoAnalytics(): GinkoAnalytics {
   const config = useGinkoDocsConfig();
-  const plausible = config.analytics?.plausible;
+  const scriptId = config.analytics?.plausible?.scriptId?.trim();
 
-  if (!plausible?.domain) {
+  if (!scriptId) {
     return { enabled: false, track: () => {} };
   }
 
   const script = useScriptPlausibleAnalytics({
-    domain: plausible.domain,
-    extension: plausible.extensions ?? ["outbound-links"],
-    ...(plausible.scriptSrc ? { scriptInput: { src: plausible.scriptSrc } } : {}),
+    scriptId,
+    // The site ID comes from app.config at runtime. Keep the vendor script
+    // external so Nuxt Scripts does not bundle its legacy fallback URL during
+    // the build-time transform.
+    scriptOptions: { bundle: false },
   });
 
   return {
     enabled: true,
     track: (event, props) => {
       if (!import.meta.client) return;
-      script.proxy.plausible(event, props ? { props } : undefined);
+      const plausible = script.proxy.plausible;
+      if (typeof plausible !== "function") return;
+      plausible(event, props ? { props } : undefined);
     },
   };
 }

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",