@lupinum/ginko-docs 0.2.2 → 0.2.5

package/app/pages/index.vue

@@ -1,42 +1,110 @@
 <script setup lang="ts">
 import { computed } from "vue";
+import { useClipboard } from "@vueuse/core";
 import { useI18n, useSeoMeta } from "#imports";
 import { getLocalizedSiteText } from "#ginko-docs/config/site.utils";
 import { useGinkoDocsConfig } from "#ginko-docs/composables/useGinkoDocsConfig";
+import SiteHeroCode from "#ginko-docs/components/site/SiteHeroCode.vue";
 
 const config = useGinkoDocsConfig();
-const { locale } = useI18n();
-const localize = (value: string | { en: string; de?: string }) =>
-  getLocalizedSiteText(value, locale.value);
+const { locale, t } = useI18n();
+
+type LocalizableText = string | { en: string; de?: string };
+const localize = (value: LocalizableText) => getLocalizedSiteText(value, locale.value);
+const localizeLink = (link: { label: LocalizableText; to: LocalizableText }) => ({
+  label: localize(link.label),
+  to: localize(link.to),
+});
+
 const landing = computed(() => ({
-  eyebrow: config.landing.eyebrow ? localize(config.landing.eyebrow) : undefined,
   title: localize(config.landing.title),
   description: localize(config.landing.description),
-  primary: {
-    label: localize(config.landing.primary.label),
-    to: localize(config.landing.primary.to),
-  },
-  secondary: config.landing.secondary
-    ? {
-        label: localize(config.landing.secondary.label),
-        to: localize(config.landing.secondary.to),
-      }
-    : undefined,
+  primary: localizeLink(config.landing.primary),
+  secondary: config.landing.secondary ? localizeLink(config.landing.secondary) : undefined,
+  install: config.landing.install,
   features: config.landing.features.map((feature) => ({
     ...feature,
     title: localize(feature.title),
     description: localize(feature.description),
   })),
   heroMedia: config.landing.hero?.media,
+  agent: config.landing.agent
+    ? {
+        title: localize(config.landing.agent.title),
+        description: localize(config.landing.agent.description),
+        code: config.landing.agent.code,
+      }
+    : undefined,
+  cta: config.landing.cta
+    ? {
+        title: localize(config.landing.cta.title),
+        primary: config.landing.cta.primary
+          ? localizeLink(config.landing.cta.primary)
+          : localizeLink(config.landing.primary),
+        secondary: config.landing.cta.secondary
+          ? localizeLink(config.landing.cta.secondary)
+          : undefined,
+      }
+    : undefined,
 }));
 
-const heroCodeLines = computed(() =>
-  landing.value.heroMedia?.type === "code" ? landing.value.heroMedia.code.split("\n") : [],
-);
+const heroCodeTabs = computed(() => {
+  const media = landing.value.heroMedia;
+
+  if (media?.type === "code-tabs") {
+    return media.tabs.map((tab) => ({ ...tab, label: localize(tab.label) }));
+  }
 
+  if (media?.type === "code") {
+    return [
+      {
+        label: media.filename ?? media.language ?? "Code",
+        filename: media.filename,
+        language: media.language,
+        code: media.code,
+      },
+    ];
+  }
+
+  return [];
+});
+
+// Feature icon tiles cycle through the theme-adaptive hero accent pairs.
+const FEATURE_TINTS = [
+  { tile: "bg-(--hero-blue-muted)", icon: "text-(--hero-blue-dark)" },
+  { tile: "bg-(--hero-mint-muted)", icon: "text-(--hero-mint-text)" },
+  { tile: "bg-(--hero-yellow-muted)", icon: "text-(--hero-yellow-dark)" },
+  { tile: "bg-(--hero-coral-muted)", icon: "text-(--hero-coral-text)" },
+];
+const tint = (index: number) => FEATURE_TINTS[index % FEATURE_TINTS.length]!;
+
+type TerminalLine = { kind: "command" | "comment" | "output"; text: string };
+const agentTerminalLines = computed<TerminalLine[]>(() => {
+  const code = landing.value.agent?.code;
+  if (!code) return [];
+
+  return code.split("\n").map((line) => ({
+    kind: line.startsWith("$")
+      ? "command"
+      : line.trimStart().startsWith("#")
+        ? "comment"
+        : "output",
+    text: line,
+  }));
+});
+
+const { copy, copied } = useClipboard();
+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>
 
@@ -47,9 +115,6 @@ useSeoMeta({
         class="relative mx-auto flex max-w-6xl flex-col gap-14 px-5 py-24 sm:px-8 sm:py-32 lg:flex-row lg:items-center"
       >
         <div class="min-w-0 flex-1">
-          <p v-if="landing.eyebrow" class="mb-6 text-sm font-semibold tracking-wide text-primary">
-            {{ landing.eyebrow }}
-          </p>
           <h1
             class="max-w-4xl text-5xl leading-[0.98] font-semibold tracking-[-0.035em] text-balance text-foreground sm:text-7xl"
             :class="landing.heroMedia ? 'lg:text-6xl' : 'lg:text-[5.75rem]'"
@@ -75,66 +140,120 @@ useSeoMeta({
               {{ landing.secondary.label }}
             </NuxtLink>
           </div>
+          <div v-if="landing.install" class="mt-5">
+            <div
+              class="inline-flex h-10 max-w-full items-center gap-3 rounded-md border border-border bg-muted/40 pr-1.5 pl-4 font-mono text-[13px] text-foreground/90"
+            >
+              <span class="text-muted-foreground select-none" aria-hidden="true">$</span>
+              <span class="truncate">{{ landing.install.command }}</span>
+              <button
+                type="button"
+                class="content-codeblock-copy-button"
+                :aria-label="copied ? t('docs.copiedText') : t('docs.copyText')"
+                @click="copyInstallCommand"
+              >
+                <Icon
+                  :name="copied ? 'lucide:check' : 'lucide:clipboard'"
+                  class="size-3.5"
+                  aria-hidden="true"
+                />
+              </button>
+            </div>
+          </div>
         </div>
 
-        <div v-if="landing.heroMedia" class="hidden w-[26rem] max-w-full shrink-0 lg:block">
+        <div
+          v-if="landing.heroMedia"
+          class="w-full min-w-0 max-w-2xl shrink-0 lg:w-[30rem] lg:max-w-full xl:w-[36rem]"
+        >
           <NuxtImg
             v-if="landing.heroMedia.type === 'image'"
             :src="landing.heroMedia.src"
             :alt="landing.heroMedia.alt"
             class="w-full rounded-xl border border-border object-cover shadow-sm"
-            width="416"
+            width="576"
             loading="lazy"
           />
-          <div
-            v-else-if="landing.heroMedia.type === 'code'"
-            class="overflow-hidden rounded-xl border border-border bg-card shadow-sm"
-          >
-            <div
-              v-if="landing.heroMedia.filename"
-              class="flex h-9 items-center gap-2 border-b border-border bg-muted/50 px-4"
-            >
-              <span class="flex gap-1.5" aria-hidden="true">
-                <span class="size-2.5 rounded-full bg-border" />
-                <span class="size-2.5 rounded-full bg-border" />
-                <span class="size-2.5 rounded-full bg-border" />
-              </span>
-              <span class="text-xs font-medium text-muted-foreground">
-                {{ landing.heroMedia.filename }}
-              </span>
-            </div>
-            <pre
-              role="region"
-              tabindex="0"
-              :aria-label="landing.heroMedia.filename ?? 'Code'"
-              class="overflow-x-auto p-4 font-mono text-[13px] leading-6 text-foreground/90 focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none"
-            ><code><span v-for="(line, index) in heroCodeLines" :key="index" class="block">{{ line }}</span></code></pre>
-          </div>
+          <SiteHeroCode v-else-if="heroCodeTabs.length" :tabs="heroCodeTabs" />
         </div>
       </div>
     </section>
 
-    <section v-if="landing.features.length" class="mx-auto max-w-6xl px-5 py-20 sm:px-8 sm:py-28">
-      <div
-        class="grid gap-12 border-t border-border pt-12 md:grid-cols-3 md:gap-0 md:divide-x md:divide-border"
-      >
+    <section v-if="landing.features.length" class="mx-auto max-w-6xl px-5 py-20 sm:px-8 sm:py-24">
+      <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
         <article
-          v-for="feature in landing.features"
+          v-for="(feature, index) in landing.features"
           :key="feature.title"
-          class="min-w-0 md:px-9 md:first:pl-0 md:last:pr-0"
+          class="min-w-0 rounded-lg border border-border bg-card p-6"
         >
-          <Icon
+          <span
             v-if="feature.icon"
-            :name="feature.icon"
-            class="size-6 text-primary"
-            aria-hidden="true"
-          />
-          <h2 class="mt-8 text-xl font-semibold tracking-tight text-foreground">
+            class="flex size-10 items-center justify-center rounded-md"
+            :class="tint(index).tile"
+          >
+            <Icon
+              :name="feature.icon"
+              class="size-5"
+              :class="tint(index).icon"
+              aria-hidden="true"
+            />
+          </span>
+          <h2 class="mt-5 text-base font-semibold tracking-tight text-foreground">
             {{ feature.title }}
           </h2>
-          <p class="mt-3 leading-7 text-muted-foreground">{{ feature.description }}</p>
+          <p class="mt-2 text-sm leading-6 text-muted-foreground">{{ feature.description }}</p>
         </article>
       </div>
     </section>
+
+    <section v-if="landing.agent" class="border-y border-border bg-agent-background">
+      <div
+        class="mx-auto grid max-w-6xl items-center gap-10 px-5 py-16 sm:px-8 sm:py-20 lg:grid-cols-2 lg:gap-16"
+      >
+        <div class="min-w-0">
+          <h2
+            class="text-3xl font-semibold tracking-[-0.03em] text-balance text-agent-foreground sm:text-4xl"
+          >
+            {{ landing.agent.title }}
+          </h2>
+          <p class="mt-4 max-w-xl text-base leading-7 text-agent-muted">
+            {{ landing.agent.description }}
+          </p>
+        </div>
+        <pre
+          class="min-w-0 overflow-x-auto rounded-lg border border-white/10 bg-black/30 p-5 font-mono text-[13px] leading-7"
+        ><code><span
+            v-for="(line, index) in agentTerminalLines"
+            :key="index"
+            class="block min-h-[1.75rem] whitespace-pre"
+          ><template v-if="line.kind === 'command'"><span class="text-agent-muted/70 select-none">$</span><span class="text-agent-foreground">{{ line.text.slice(1) }}</span></template><span v-else-if="line.kind === 'comment'" class="text-emerald-300/90">{{ line.text }}</span><span v-else class="text-agent-muted">{{ line.text }}</span></span></code></pre>
+      </div>
+    </section>
+
+    <section v-if="landing.cta">
+      <div class="mx-auto max-w-6xl px-5 py-20 text-center sm:px-8 sm:py-28">
+        <h2
+          class="text-3xl font-semibold tracking-[-0.03em] text-balance text-foreground sm:text-5xl"
+        >
+          {{ landing.cta.title }}
+        </h2>
+        <div class="mt-9 flex flex-wrap items-center justify-center gap-3">
+          <NuxtLink
+            :to="landing.cta.primary.to"
+            class="inline-flex h-11 items-center gap-2 rounded-md bg-primary px-5 text-sm font-semibold text-primary-foreground transition-transform hover:-translate-y-0.5"
+          >
+            {{ landing.cta.primary.label }}
+            <Icon name="lucide:arrow-right" class="size-4" aria-hidden="true" />
+          </NuxtLink>
+          <NuxtLink
+            v-if="landing.cta.secondary"
+            :to="landing.cta.secondary.to"
+            class="inline-flex h-11 items-center gap-2 rounded-md border border-border bg-background px-5 text-sm font-semibold text-foreground transition-colors hover:bg-muted"
+          >
+            {{ landing.cta.secondary.label }}
+          </NuxtLink>
+        </div>
+      </div>
+    </section>
   </div>
 </template>

package/app/plugins/ginko-docs-theme.ts

@@ -0,0 +1,12 @@
+import { defineNuxtPlugin, useAppConfig, useHead } from "#imports";
+
+export default defineNuxtPlugin(() => {
+  const { theme } = useAppConfig().ginkoDocs;
+
+  useHead({
+    htmlAttrs: {
+      "data-neutral": theme.neutral,
+      "data-primary": theme.primary,
+    },
+  });
+});

package/app/utils/content.ts

@@ -12,6 +12,17 @@ export type FlatTocItem = {
   depth?: number;
 };
 
+export function getMarkdownTocLinks(body: unknown): TocLinkLike[] | undefined {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return undefined;
+
+  const root = body as { type?: unknown; children?: unknown; toc?: unknown };
+  if (root.type !== "root" || !Array.isArray(root.children)) return undefined;
+  if (!root.toc || typeof root.toc !== "object" || Array.isArray(root.toc)) return undefined;
+
+  const links = (root.toc as { links?: unknown }).links;
+  return Array.isArray(links) ? (links as TocLinkLike[]) : undefined;
+}
+
 export function formatContentDate(
   value?: string | Date | null,
   locale: string = defaultLocale,

package/app/utils/file-icons.ts

@@ -0,0 +1,90 @@
+export const FALLBACK_FILE_ICON = "lucide:file";
+
+export const FILENAME_ICONS: Record<string, string> = {
+  ".env": "lucide:file-key",
+  ".env.example": "lucide:file-key",
+  ".gitignore": "lucide:git-branch",
+  "components.json": "lucide:blocks",
+  "eslint.config.cjs": "lucide:badge-check",
+  "eslint.config.js": "lucide:badge-check",
+  "eslint.config.mjs": "lucide:badge-check",
+  "nuxt.config.js": "logos:nuxt-icon",
+  "nuxt.config.ts": "logos:nuxt-icon",
+  "package.json": "lucide:package",
+  "pnpm-lock.yaml": "lucide:package",
+  "pnpm-workspace.yaml": "lucide:package",
+  "tailwind.config.js": "lucide:palette",
+  "tailwind.config.ts": "lucide:palette",
+  "tsconfig.json": "lucide:file-cog",
+  "vite.config.js": "lucide:zap",
+  "vite.config.ts": "lucide:zap",
+};
+
+export const EXTENSION_ICONS: Record<string, string> = {
+  bash: "lucide:terminal",
+  cjs: "lucide:file-json",
+  css: "lucide:braces",
+  csv: "lucide:table",
+  htm: "lucide:code-xml",
+  html: "lucide:code-xml",
+  js: "lucide:file-json",
+  json: "lucide:braces",
+  jsx: "lucide:atom",
+  md: "lucide:file-text",
+  mdc: "lucide:file-text",
+  mjs: "lucide:file-json",
+  mts: "lucide:file-code",
+  scss: "lucide:braces",
+  sh: "lucide:terminal",
+  ts: "logos:typescript-icon",
+  tsx: "lucide:atom",
+  txt: "lucide:file-text",
+  vue: "logos:vue",
+  yaml: "lucide:file-cog",
+  yml: "lucide:file-cog",
+};
+
+export const LANGUAGE_ICONS: Record<string, string> = {
+  bash: "lucide:terminal",
+  css: "lucide:braces",
+  html: "lucide:code-xml",
+  javascript: "lucide:file-json",
+  js: "lucide:file-json",
+  json: "lucide:braces",
+  jsx: "lucide:atom",
+  markdown: "lucide:file-text",
+  mdc: "lucide:file-text",
+  shell: "lucide:terminal",
+  sh: "lucide:terminal",
+  ts: "logos:typescript-icon",
+  tsx: "lucide:atom",
+  typescript: "logos:typescript-icon",
+  vue: "logos:vue",
+  "vue-html": "logos:vue",
+  yaml: "lucide:file-cog",
+  yml: "lucide:file-cog",
+};
+
+export function normalizedFilename(filename: string | null | undefined): string | null {
+  return filename?.trim().replace(/^\.\//, "").toLowerCase() || null;
+}
+
+export function filenameExtension(filename: string | null | undefined): string | null {
+  const normalized = normalizedFilename(filename);
+  const basename = normalized?.split("/").pop();
+  const index = basename?.lastIndexOf(".") ?? -1;
+
+  if (!basename || index < 0 || index === basename.length - 1) return null;
+  return basename.slice(index + 1);
+}
+
+/** Best-effort icon for a file, by exact name first, then extension. */
+export function resolveFileIcon(filename: string | null | undefined): string {
+  const normalized = normalizedFilename(filename);
+  if (normalized && FILENAME_ICONS[normalized]) return FILENAME_ICONS[normalized];
+
+  const extension = filenameExtension(filename);
+  if (extension && EXTENSION_ICONS[extension]) return EXTENSION_ICONS[extension];
+
+  return FALLBACK_FILE_ICON;
+}

package/app/utils/index.ts

@@ -1 +1,7 @@
-export { cn } from "../../runtime/utils";
+import type { ClassValue } from "clsx";
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/app/utils/repository.ts

@@ -0,0 +1,20 @@
+import type { GinkoDocsAppConfig } from "../../shared/types/app-config";
+
+type RepositoryConfig = NonNullable<GinkoDocsAppConfig["repository"]>;
+
+const repoBase = (repository: RepositoryConfig) => repository.url.replace(/\/$/, "");
+
+export function buildRepoIssueUrl(
+  repository: RepositoryConfig,
+  params: { title: string; body: string },
+): string {
+  const url = new URL(`${repoBase(repository)}/issues/new`);
+  url.searchParams.set("title", params.title);
+  url.searchParams.set("body", params.body);
+  return url.toString();
+}
+
+export function buildRepoEditUrl(repository: RepositoryConfig, sourcePath: string): string {
+  const branch = repository.branch || "main";
+  return `${repoBase(repository)}/edit/${encodeURIComponent(branch)}/${sourcePath}`;
+}

package/content.js

@@ -1,5 +1,4 @@
 import {
-  defineAgentAppPage,
   defineAgentMetadataFields,
   defineAgentSection,
   defineCollection,
@@ -24,31 +23,54 @@ const routeSlugs = {
 };
 //#endregion
 //#region layer/content.ts
-const docsSchema = z.object({
-  title: z.string(),
-  description: z.string(),
-  icon: z.string().optional(),
-  badge: z.string().optional(),
-  updated: z.string().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: z.string(),
-  readingTime: z.string(),
-  author: reference("authors"),
-  image: z.string().optional(),
-});
+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 = (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(),
@@ -66,10 +88,13 @@ const authorsSchema = z.object({
 });
 function defineGinkoDocsConfig(options) {
   const locales = options.locales ?? ["en"];
-  const defaultLocale = options.defaultLocale ?? locales[0] ?? "en";
-  const i18n = locales.length > 1;
-  const routeMap = (key) =>
-    Object.fromEntries(locales.map((locale) => [locale, routeSlugs[key][locale]]));
+  if (
+    !(locales.length === 1
+      ? locales[0] === "en"
+      : locales.length === 2 && locales[0] === "en" && locales[1] === "de")
+  )
+    throw new TypeError('locales must be exactly ["en"] or ["en", "de"]');
+  const i18n = locales.length === 2;
   const metadata = defineAgentMetadataFields([
     "title",
     "description",
@@ -85,25 +110,25 @@ function defineGinkoDocsConfig(options) {
     type: "page",
     source: i18n ? "{1.docs,1.dokumentation}/**/*.md" : "docs/**/*.md",
     i18n: i18n ? true : void 0,
-    route: i18n ? routeMap("docs") : routeSlugs.docs[defaultLocale],
+    route: i18n ? routeSlugs.docs : routeSlugs.docs.en,
     agent: {
       section: "optional",
       markdown: true,
     },
     strict: true,
-    schema: docsSchema,
+    schema: docsSchemaWithLastmod,
   });
   const blog = defineCollection({
     type: "page",
-    source: "2.blog/**/*.md",
+    source: "2.blog/*.md",
     i18n: i18n ? true : void 0,
-    route: i18n ? routeMap("blog") : routeSlugs.blog[defaultLocale],
+    route: i18n ? routeSlugs.blog : routeSlugs.blog.en,
     agent: {
       section: "blog",
       markdown: true,
     },
     strict: true,
-    schema: blogSchema,
+    schema: blogSchemaWithLastmod,
   });
   const authors = defineCollection({
     type: "data",
@@ -131,30 +156,23 @@ function defineGinkoDocsConfig(options) {
           ? [
               defineAgentSection({
                 id: "blog",
-                title: "Blog",
+                title: {
+                  en: "Blog",
+                  de: "Blog",
+                },
                 order: 40,
               }),
             ]
           : []),
         defineAgentSection({
           id: "optional",
-          title: "Documentation",
+          title: {
+            en: "Documentation",
+            de: "Dokumentation",
+          },
           order: 100,
         }),
       ],
-      pages: [
-        defineAgentAppPage({
-          id: "home",
-          route: Object.fromEntries(
-            locales.map((locale) => [locale, locale === defaultLocale ? "/" : `/${locale}`]),
-          ),
-          section: "optional",
-          title: options.site.name,
-          description: options.site.description,
-          metadata,
-          render: () => `# ${options.site.name}\n\n> ${options.site.description}`,
-        }),
-      ],
     },
   };
   if (options.blog)