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

package/app/error.vue

@@ -3,8 +3,8 @@ import { localizedRoutes } from "../i18n/routes";
 import { messages } from "../i18n/messages/index";
 import { normalizeAppError } from "./lib/errors";
 import { computed } from "vue";
-import { clearError, useHead } from "#imports";
-import { localeFromPath, localizedPath } from "../i18n/locales";
+import { clearError, useHead, useRequestURL, useRuntimeConfig } from "#imports";
+import { defaultLocale, isLocaleCode, localeFromPath, localizedPath } from "../i18n/locales";
 
 type NuxtErrorLike = {
   message?: string;
@@ -19,17 +19,26 @@ const props = defineProps<{
   error: NuxtErrorLike;
 }>();
 
+const configuredPrimaryLocale = useRuntimeConfig().public.ginkoDocs?.primaryLocale;
+const primaryLocale =
+  typeof configuredPrimaryLocale === "string" && isLocaleCode(configuredPrimaryLocale)
+    ? configuredPrimaryLocale
+    : defaultLocale;
+
 const normalized = computed(() => normalizeAppError(props.error));
-const requestPath = computed(
-  () => props.error?.url || (import.meta.client ? window.location.pathname : "/"),
-);
-const locale = computed(() => localeFromPath(requestPath.value));
+const requestUrl = useRequestURL();
+const requestPath = computed(() => props.error?.url || requestUrl.pathname);
+const locale = computed(() => localeFromPath(requestPath.value, primaryLocale));
 const copy = computed(() => {
   const catalog = messages[locale.value].errors;
   return catalog[normalized.value.kind] ?? catalog.unavailable;
 });
-const homePath = computed(() => localizedPath(locale.value, localizedRoutes[locale.value].home));
-const docsPath = computed(() => localizedPath(locale.value, localizedRoutes[locale.value].docs));
+const homePath = computed(() =>
+  localizedPath(locale.value, localizedRoutes[locale.value].home, primaryLocale),
+);
+const docsPath = computed(() =>
+  localizedPath(locale.value, localizedRoutes[locale.value].docs, primaryLocale),
+);
 const title = computed(() => `${normalized.value.statusCode} - ${copy.value.title}`);
 // Keep the full site chrome for content-level errors (404 and friends); hard
 // server failures fall back to the bare page so the error screen cannot crash.
@@ -37,6 +46,7 @@ const showChrome = computed(() => normalized.value.kind !== "server");
 
 useHead(() => ({
   title: title.value,
+  htmlAttrs: { lang: locale.value },
   meta: [{ name: "robots", content: "noindex, nofollow" }],
 }));
 

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

@@ -165,7 +165,7 @@ function scrollToTop() {
         <article v-if="page">
           <div class="flex items-start justify-between gap-4 sm:gap-6">
             <div class="min-w-0">
-              <DocsBreadcrumb class="mb-2" :items="visibleTrail" />
+              <DocsBreadcrumb v-if="visibleTrail.length > 1" class="mb-2" :items="visibleTrail" />
               <h1
                 class="font-heading text-[27px] leading-[1.15] font-semibold tracking-[-0.02em] text-balance text-foreground"
               >
@@ -208,7 +208,7 @@ function scrollToTop() {
 
     <aside
       ref="tocAside"
-      class="sticky top-[var(--site-header-height)] hidden h-[calc(100dvh-var(--site-header-height)-var(--site-banner-height,0px))] w-[var(--docs-toc-width)] shrink-0 flex-col overflow-y-auto pt-10 pr-4 pb-6 xl:flex"
+      class="docs-toc-shell sticky top-[var(--site-header-height)] h-[calc(100dvh-var(--site-header-height)-var(--site-banner-height,0px))] w-[var(--docs-toc-width)] shrink-0 flex-col overflow-y-auto pt-10 pr-4 pb-6"
       :aria-label="t('docs.toc')"
     >
       <DocsToc class="mb-6" :items="tocItems" :active-ids="activeIds" />

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

@@ -48,13 +48,13 @@ const linkRowClass = computed(() =>
     "group relative flex w-full flex-row items-center gap-2 text-start [overflow-wrap:anywhere] text-muted-foreground transition-colors outline-none focus-visible:ring-2 focus-visible:ring-ring",
     "[&_svg]:size-4 [&_svg]:shrink-0",
     "hover:bg-accent/50 hover:text-accent-foreground/80 hover:transition-none",
-    "data-[active=true]:bg-primary/10 data-[active=true]:text-primary data-[active=true]:font-medium data-[active=true]:hover:transition-colors",
+    "data-[active=true]:bg-muted data-[active=true]:text-foreground data-[active=true]:font-medium data-[active=true]:hover:bg-muted data-[active=true]:hover:transition-colors",
     props.depth === 0
       ? "rounded-[7px] px-2 py-[5.5px] text-[13px]"
       : cn(
           "rounded-e-[7px] border-s border-border py-[5px] pe-2 text-[12.5px]",
           "hover:border-s-muted-foreground/40",
-          "data-[active=true]:border-s-primary",
+          "data-[active=true]:border-s-brand",
           paddingClass.value,
         ),
   ),

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

@@ -21,7 +21,7 @@ const emit = defineEmits<{
         class="flex min-h-9 w-full items-center gap-2 rounded-lg px-2 text-start text-sm transition-colors outline-none focus-visible:ring-2 focus-visible:ring-ring"
         :class="
           activeId === section.id
-            ? 'bg-accent font-medium text-foreground'
+            ? 'bg-muted font-medium text-foreground'
             : 'text-muted-foreground hover:bg-accent/50 hover:text-foreground'
         "
         :aria-pressed="activeId === section.id"

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

@@ -76,7 +76,7 @@ function scrollToHeading(id: string) {
 
     <div class="relative border-l border-border pl-3">
       <div
-        class="pointer-events-none absolute -left-px w-0.5 rounded-full bg-primary transition-all duration-200 ease-out"
+        class="pointer-events-none absolute -left-px w-0.5 rounded-full bg-brand transition-all duration-200 ease-out"
         :style="indicatorStyle"
       />
 
@@ -91,7 +91,7 @@ function scrollToHeading(id: string) {
               cn(
                 item.depth === 3 ? 'pl-3' : (item.depth ?? 2) >= 4 ? 'pl-6' : '',
                 activeIds.includes(item.id)
-                  ? 'font-medium text-primary'
+                  ? 'font-medium text-foreground'
                   : 'text-muted-foreground hover:text-foreground',
               )
             "

package/app/features/search/command-center.ts

@@ -24,6 +24,39 @@ export interface CommandCenterGroupResult {
 export const MAX_RECENT_ITEMS = 5;
 export const PAGE_HIGHLIGHT_STORAGE_KEY = "site-command-center-page-highlight";
 
+const SEARCH_HIGHLIGHT_STOP_WORDS = new Set([
+  "a",
+  "an",
+  "and",
+  "der",
+  "die",
+  "das",
+  "ein",
+  "eine",
+  "for",
+  "in",
+  "of",
+  "or",
+  "the",
+  "to",
+  "und",
+  "von",
+  "zu",
+]);
+
+export function getSearchHighlightTerms(query: string): string[] {
+  const terms = [...new Set(query.trim().toLocaleLowerCase().split(/\s+/).filter(Boolean))];
+  const meaningfulTerms = terms.filter(
+    (term) => term.length > 1 && !SEARCH_HIGHLIGHT_STOP_WORDS.has(term),
+  );
+
+  return meaningfulTerms.length > 0 ? meaningfulTerms : terms;
+}
+
+export function shouldShowSearchResultBadges(items: CommandCenterItem[]): boolean {
+  return new Set(items.map((item) => item.badge).filter(Boolean)).size > 1;
+}
+
 export function dedupeCommandCenterItems(items: CommandCenterItem[]) {
   const seen = new Set<string>();
   return items.filter((item) => {

package/app/features/search/components/SiteCommandCenter.vue

@@ -2,6 +2,10 @@
 import { computed, nextTick, onMounted, ref, useTemplateRef, watch } from "vue";
 import { useI18n, useRoute } from "#imports";
 import { useCommandCenter } from "#ginko-docs/features/search/useCommandCenter";
+import {
+  getSearchHighlightTerms,
+  shouldShowSearchResultBadges,
+} from "#ginko-docs/features/search/command-center";
 import {
   DialogContent,
   DialogDescription,
@@ -21,10 +25,13 @@ const { open, query, groupedItems, searchPending, searchError, searchIsEmpty, se
 
 const visibleItems = computed(() => groupedItems.value.flatMap((g) => g.items));
 const isSearching = computed(() => query.value.trim().length > 0);
+const showResultBadges = computed(
+  () => !isSearching.value || shouldShowSearchResultBadges(visibleItems.value),
+);
 
 // ── text highlighting ──────────────────────────────────────────────────────
 function highlightTokens(text: string, q: string): { text: string; match: boolean }[] {
-  const terms = q.trim().split(/\s+/).filter(Boolean);
+  const terms = getSearchHighlightTerms(q);
   if (terms.length === 0) return [{ text, match: false }];
   const pattern = terms.map((term) => term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
   return text
@@ -123,7 +130,7 @@ onMounted(async () => {
         class="fixed inset-0 z-50 bg-overlay backdrop-blur-sm data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:animate-in data-[state=open]:fade-in-0"
       />
       <DialogContent
-        class="fixed top-[8vh] left-1/2 z-50 flex max-h-[84vh] w-[min(94vw,46rem)] -translate-x-1/2 flex-col overflow-hidden rounded-xl border border-border bg-background shadow-lg outline-none data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 sm:top-[10vh]"
+        class="fixed top-[8vh] left-1/2 z-50 flex max-h-[80vh] w-[min(94vw,44rem)] -translate-x-1/2 flex-col overflow-hidden rounded-xl border border-border bg-background shadow-lg outline-none data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 sm:top-[10vh]"
         @keydown="handleListNavigation"
       >
         <VisuallyHidden>
@@ -165,7 +172,9 @@ onMounted(async () => {
         </div>
 
         <!-- Results -->
-        <div class="min-h-0 flex-1 overflow-y-auto overscroll-contain py-2">
+        <div
+          class="min-h-0 flex-1 overflow-y-auto overscroll-contain py-2 [scrollbar-color:var(--border)_transparent]"
+        >
           <div
             v-if="isSearching && searchPending"
             class="flex items-center justify-center gap-2 px-6 py-12 text-sm text-muted-foreground"
@@ -190,6 +199,13 @@ onMounted(async () => {
               <div class="flex items-center gap-2 px-2 pt-1.5 pb-1">
                 <span class="text-[11px] font-medium text-muted-foreground">{{ group.title }}</span>
                 <div class="flex-1 border-t border-border/60" />
+                <span
+                  v-if="group.id === 'search'"
+                  class="text-[11px] tabular-nums text-muted-foreground"
+                  aria-live="polite"
+                >
+                  {{ t("command.resultCount", { count: group.items.length }) }}
+                </span>
               </div>
 
               <button
@@ -198,7 +214,7 @@ onMounted(async () => {
                 type="button"
                 :data-item="item.id"
                 :aria-label="itemLabel(item)"
-                class="group flex w-full items-start gap-3 rounded-lg px-2.5 py-2.5 text-left transition-colors outline-none"
+                class="group flex w-full items-start gap-3 rounded-lg px-2.5 py-2 text-left transition-colors outline-none"
                 :class="
                   highlightedId === item.id ? 'bg-accent text-accent-foreground' : 'text-foreground'
                 "
@@ -208,7 +224,7 @@ onMounted(async () => {
               >
                 <!-- Icon -->
                 <div
-                  class="mt-0.5 flex size-9 shrink-0 items-center justify-center rounded-md border border-border bg-muted/50 transition-colors"
+                  class="mt-0.5 flex size-8 shrink-0 items-center justify-center rounded-md border border-border bg-muted/50 transition-colors"
                   :class="highlightedId === item.id ? 'border-border/80 bg-background' : ''"
                 >
                   <Icon
@@ -235,14 +251,14 @@ onMounted(async () => {
                       >
                         <mark
                           v-if="token.match"
-                          class="rounded-[3px] bg-primary/15 font-medium text-primary not-italic"
+                          class="rounded-[3px] bg-accent-yellow px-0.5 font-medium text-accent-yellow-foreground not-italic"
                           >{{ token.text }}</mark
                         ><template v-else>{{ token.text }}</template>
                       </template>
                     </span>
                     <span
-                      v-if="item.badge"
-                      class="shrink-0 rounded-full bg-primary/10 px-1.5 py-px text-[10px] font-medium text-primary"
+                      v-if="item.badge && showResultBadges"
+                      class="shrink-0 rounded-full bg-muted px-1.5 py-px text-[10px] font-medium text-muted-foreground"
                     >
                       {{ item.badge }}
                     </span>
@@ -263,7 +279,7 @@ onMounted(async () => {
                       >
                         <mark
                           v-if="token.match"
-                          class="rounded-[3px] bg-primary/15 font-medium text-primary not-italic"
+                          class="rounded-[3px] bg-accent-yellow px-0.5 font-medium text-accent-yellow-foreground not-italic"
                           >{{ token.text }}</mark
                         ><template v-else>{{ token.text }}</template>
                       </template>

package/app/features/search/components/SiteSearchPageHighlight.vue

@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { nextTick, onBeforeUnmount, watch } from "vue";
 import { useRoute } from "#imports";
+import { getSearchHighlightTerms } from "#ginko-docs/features/search/command-center";
 
 const STORAGE_KEY = "site-command-center-page-highlight";
 const HIGHLIGHT_SELECTOR = "mark[data-search-page-highlight]";
@@ -65,7 +66,8 @@ function highlightPattern(root: Element, pattern: RegExp) {
 
       const mark = document.createElement("mark");
       mark.dataset.searchPageHighlight = "";
-      mark.className = "rounded-[3px] bg-primary/15 px-0.5 text-primary";
+      mark.className =
+        "rounded-[3px] bg-accent-yellow px-0.5 font-medium text-accent-yellow-foreground";
       mark.textContent = value;
       fragment.append(mark);
 
@@ -83,7 +85,7 @@ function escapePattern(value: string) {
 
 function buildPatterns(query: string) {
   const phrase = query.trim().replace(/\s+/g, " ");
-  const tokens = phrase.split(/\s+/).filter((token) => token.length > 2);
+  const tokens = getSearchHighlightTerms(phrase);
   const phrasePattern = phrase.split(/\s+/).map(escapePattern).join("\\s+");
 
   return [

package/app/features/search/useCommandCenter.ts

@@ -71,7 +71,7 @@ export async function useCommandCenter() {
   // Nuxt/i18n composable after an awaited operation loses the setup context.
   const docsNavigationResult = useDocsNavigation();
   const contentSearchResult = useContentSearch({
-    limit: 12,
+    limit: 8,
     locale: () => locale.value,
   });
   const [
@@ -190,7 +190,7 @@ export async function useCommandCenter() {
             href: github.href,
             external: true,
             group: "actions" as const,
-            icon: github.icon ?? "lucide:github",
+            icon: github.icon ?? "ginko-social:github",
             keywords: ["repo", "source", "code"],
           },
         ]

package/app/layouts/docs.vue

@@ -6,7 +6,7 @@
 
     <div class="mx-auto flex w-full max-w-screen-2xl min-w-0 flex-1">
       <div
-        class="pointer-events-none sticky top-[var(--site-header-height)] z-20 hidden h-[calc(100dvh-var(--site-header-height)-var(--site-banner-height,0px))] w-[var(--docs-sidebar-width)] shrink-0 overflow-hidden *:pointer-events-auto md:block"
+        class="docs-sidebar-shell pointer-events-none sticky top-[var(--site-header-height)] z-20 h-[calc(100dvh-var(--site-header-height)-var(--site-banner-height,0px))] w-[var(--docs-sidebar-width)] shrink-0 overflow-hidden *:pointer-events-auto"
       >
         <DocsSidebar />
       </div>

package/app/pages/index.vue

@@ -69,6 +69,11 @@ const heroCodeTabs = computed(() => {
   return [];
 });
 
+const hasWideHeroCode = computed(() => {
+  const media = landing.value.heroMedia;
+  return media?.type !== "image" && media?.layout === "wide";
+});
+
 // Feature icon tiles cycle through the theme-adaptive hero accent pairs.
 const FEATURE_TINTS = [
   { tile: "bg-(--hero-blue-muted)", icon: "text-(--hero-blue-dark)" },
@@ -127,7 +132,7 @@ useSeoMeta({
           <div class="mt-10 flex flex-wrap items-center gap-3">
             <NuxtLink
               :to="landing.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"
+              class="inline-flex h-11 items-center gap-2 rounded-md bg-brand px-5 text-sm font-semibold text-brand-foreground transition-transform hover:-translate-y-0.5"
             >
               {{ landing.primary.label }}
               <Icon name="lucide:arrow-right" class="size-4" aria-hidden="true" />
@@ -174,7 +179,11 @@ useSeoMeta({
             width="576"
             loading="lazy"
           />
-          <SiteHeroCode v-else-if="heroCodeTabs.length" :tabs="heroCodeTabs" />
+          <SiteHeroCode
+            v-else-if="heroCodeTabs.length"
+            :tabs="heroCodeTabs"
+            :class="hasWideHeroCode && 'site-hero-code-wide'"
+          />
         </div>
       </div>
     </section>
@@ -240,7 +249,7 @@ useSeoMeta({
         <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"
+            class="inline-flex h-11 items-center gap-2 rounded-md bg-brand px-5 text-sm font-semibold text-brand-foreground transition-transform hover:-translate-y-0.5"
           >
             {{ landing.cta.primary.label }}
             <Icon name="lucide:arrow-right" class="size-4" aria-hidden="true" />
@@ -257,3 +266,13 @@ useSeoMeta({
     </section>
   </div>
 </template>
+
+<style scoped>
+/* Keep the hero grid intact; only use spare space toward the viewport edge. */
+@media (min-width: 80rem) {
+  .site-hero-code-wide {
+    width: min(48.75rem, calc(50vw - 2rem));
+    max-width: none;
+  }
+}
+</style>

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

@@ -5,6 +5,7 @@ export default defineNuxtPlugin(() => {
 
   useHead({
     htmlAttrs: {
+      "data-theme-preset": theme.preset ?? "default",
       "data-neutral": theme.neutral,
       "data-primary": theme.primary,
       "data-code-blocks": theme.codeBlocks,

package/content-collections.ts

@@ -1,4 +1,5 @@
 import { defineCollection, defineContentConfig, reference } from "@lupinum/ginko-content/config";
+import type { ContentAgentCollectionConfig } from "@lupinum/ginko-content/config";
 import { z } from "zod";
 import { routeSlugs } from "./shared/route-slugs";
 
@@ -51,15 +52,22 @@ const authorsSchema = z.object({
   links: z.array(z.object({ label: z.string(), href: z.string() })).optional(),
 });
 
-export function createGinkoDocsCollections(i18n: boolean) {
+export function createGinkoDocsCollections(
+  locales: readonly ["en"] | readonly ["de"] | readonly ["en", "de"] = ["en"],
+  docsMarkdown: ContentAgentCollectionConfig["markdown"] = true,
+) {
+  const i18n = locales.length === 2;
+  const primaryLocale = locales[0];
   return defineContentConfig({
     collections: {
       docs: defineCollection({
         type: "page",
-        source: i18n ? "{1.docs,1.dokumentation}/**/*.md" : "docs/**/*.md",
+        source: i18n
+          ? "{1.docs,1.dokumentation}/**/*.md"
+          : `${routeSlugs.docs[primaryLocale].slice(1)}/**/*.md`,
         i18n: i18n ? true : undefined,
-        route: i18n ? routeSlugs.docs : routeSlugs.docs.en,
-        agent: { section: "optional", markdown: true },
+        route: i18n ? routeSlugs.docs : routeSlugs.docs[primaryLocale],
+        agent: { section: "optional", markdown: docsMarkdown },
         strict: true,
         schema: docsSchemaWithLastmod,
       }),
@@ -67,7 +75,7 @@ export function createGinkoDocsCollections(i18n: boolean) {
         type: "page",
         source: "2.blog/*.md",
         i18n: i18n ? true : undefined,
-        route: i18n ? routeSlugs.blog : routeSlugs.blog.en,
+        route: i18n ? routeSlugs.blog : routeSlugs.blog[primaryLocale],
         agent: { section: "blog", markdown: true },
         strict: true,
         schema: blogSchemaWithLastmod,

package/content.js

@@ -81,17 +81,21 @@ const authorsSchema = z.object({
     )
     .optional(),
 });
-function createGinkoDocsCollections(i18n) {
+function createGinkoDocsCollections(locales = ["en"], docsMarkdown = true) {
+  const i18n = locales.length === 2;
+  const primaryLocale = locales[0];
   return defineContentConfig({
     collections: {
       docs: defineCollection({
         type: "page",
-        source: i18n ? "{1.docs,1.dokumentation}/**/*.md" : "docs/**/*.md",
+        source: i18n
+          ? "{1.docs,1.dokumentation}/**/*.md"
+          : `${routeSlugs.docs[primaryLocale].slice(1)}/**/*.md`,
         i18n: i18n ? true : void 0,
-        route: i18n ? routeSlugs.docs : routeSlugs.docs.en,
+        route: i18n ? routeSlugs.docs : routeSlugs.docs[primaryLocale],
         agent: {
           section: "optional",
-          markdown: true,
+          markdown: docsMarkdown,
         },
         strict: true,
         schema: docsSchemaWithLastmod,
@@ -100,7 +104,7 @@ function createGinkoDocsCollections(i18n) {
         type: "page",
         source: "2.blog/*.md",
         i18n: i18n ? true : void 0,
-        route: i18n ? routeSlugs.blog : routeSlugs.blog.en,
+        route: i18n ? routeSlugs.blog : routeSlugs.blog[primaryLocale],
         agent: {
           section: "blog",
           markdown: true,
@@ -125,11 +129,10 @@ function defineGinkoDocsConfig(options) {
   const locales = options.locales ?? ["en"];
   if (
     !(locales.length === 1
-      ? locales[0] === "en"
+      ? locales[0] === "en" || locales[0] === "de"
       : 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;
+    throw new TypeError('locales must be exactly ["en"], ["de"], or ["en", "de"]');
   const metadata = defineAgentMetadataFields([
     "title",
     "description",
@@ -141,13 +144,14 @@ function defineGinkoDocsConfig(options) {
     "source",
     "updated",
   ]);
-  const { docs, blog, authors } = createGinkoDocsCollections(i18n);
+  const { docs, blog, authors } = createGinkoDocsCollections(locales, options.agent?.documentation);
   const config = {
     agent: {
       site: {
         title: options.site.name,
         description: options.site.description,
-        url: options.site.url,
+        whenToUse: options.site.whenToUse,
+        ...(options.site.whenNotToUse ? { whenNotToUse: options.site.whenNotToUse } : {}),
       },
       markdown: {
         metadata: {
@@ -156,6 +160,7 @@ function defineGinkoDocsConfig(options) {
         },
       },
       sections: [
+        ...(options.agent?.sections ?? []),
         ...(options.blog
           ? [
               defineAgentSection({
@@ -177,6 +182,7 @@ function defineGinkoDocsConfig(options) {
           order: 100,
         }),
       ],
+      ...(options.agent?.pages ? { pages: [...options.agent.pages] } : {}),
     },
   };
   if (options.blog)

package/content.ts

@@ -1,18 +1,33 @@
 import {
+  defineAgentAppPage,
   defineAgentMetadataFields,
   defineAgentSection,
   defineContentConfig,
 } from "@lupinum/ginko-content/config";
-import type { ContentConfig } from "@lupinum/ginko-content/config";
+import type { ContentAgentMarkdownOptions, ContentConfig } from "@lupinum/ginko-content/config";
 import { createGinkoDocsCollections } from "./content-collections";
 
+type GinkoDocsAgentPage = Parameters<typeof defineAgentAppPage>[0];
+type GinkoDocsAgentSection = Parameters<typeof defineAgentSection>[0];
+
+export interface GinkoDocsAgentOptions {
+  /** Control whether authored documentation appears in compact and full indexes. */
+  documentation?: ContentAgentMarkdownOptions;
+  /** Add compact index pages that point agents to canonical raw Markdown. */
+  pages?: readonly GinkoDocsAgentPage[];
+  /** Add sections before the built-in blog and optional documentation sections. */
+  sections?: readonly GinkoDocsAgentSection[];
+}
+
 export interface GinkoDocsContentOptions {
   site: {
     name: string | { en: string; de: string };
     description: string | { en: string; de: string };
-    url: string;
+    whenToUse: string | { en: string; de: string };
+    whenNotToUse?: string | { en: string; de: string };
   };
-  locales?: readonly ["en"] | readonly ["en", "de"];
+  agent?: GinkoDocsAgentOptions;
+  locales?: readonly ["en"] | readonly ["de"] | readonly ["en", "de"];
   blog?: boolean;
 }
 
@@ -37,12 +52,11 @@ export function defineGinkoDocsConfig(
   const locales = options.locales ?? ["en"];
   const validLocales =
     locales.length === 1
-      ? locales[0] === "en"
+      ? locales[0] === "en" || locales[0] === "de"
       : locales.length === 2 && locales[0] === "en" && locales[1] === "de";
   if (!validLocales) {
-    throw new TypeError('locales must be exactly ["en"] or ["en", "de"]');
+    throw new TypeError('locales must be exactly ["en"], ["de"], or ["en", "de"]');
   }
-  const i18n = locales.length === 2;
   const metadata = defineAgentMetadataFields([
     "title",
     "description",
@@ -54,16 +68,18 @@ export function defineGinkoDocsConfig(
     "source",
     "updated",
   ]);
-  const { docs, blog, authors } = createGinkoDocsCollections(i18n);
+  const { docs, blog, authors } = createGinkoDocsCollections(locales, options.agent?.documentation);
   const config = {
     agent: {
       site: {
         title: options.site.name,
         description: options.site.description,
-        url: options.site.url,
+        whenToUse: options.site.whenToUse,
+        ...(options.site.whenNotToUse ? { whenNotToUse: options.site.whenNotToUse } : {}),
       },
       markdown: { metadata: { enabled: true, defaultFields: metadata } },
       sections: [
+        ...(options.agent?.sections ?? []),
         ...(options.blog
           ? [defineAgentSection({ id: "blog", title: { en: "Blog", de: "Blog" }, order: 40 })]
           : []),
@@ -73,6 +89,7 @@ export function defineGinkoDocsConfig(
           order: 100,
         }),
       ],
+      ...(options.agent?.pages ? { pages: [...options.agent.pages] } : {}),
     },
   };
 

package/i18n/messages/global/command.ts

@@ -23,6 +23,7 @@ export const command = {
     actions: { de: "Aktionen", en: "Actions" },
   },
   loading: { de: "Suche läuft …", en: "Searching…" },
+  resultCount: { de: "{count} Treffer", en: "{count} results" },
   error: {
     de: "Die Suche ist gerade nicht verfügbar. Versuche es erneut.",
     en: "Search is temporarily unavailable. Please try again.",

package/icon-bundle.ts

@@ -3,8 +3,9 @@ import { createRequire } from "node:module";
 export const layerIconNames = [
   "circle-flags:de",
   "circle-flags:us",
+  "ginko-social:discord",
+  "ginko-social:github",
   "logos:bun",
-  "logos:discord-icon",
   "logos:npm-icon",
   "logos:nuxt-icon",
   "logos:pnpm",
@@ -91,6 +92,25 @@ type IconCollection = {
 
 const require = createRequire(import.meta.url);
 
-export const layerIconCollections = ["circle-flags", "logos", "lucide"].map(
-  (prefix) => require(`@iconify-json/${prefix}/icons.json`) as IconCollection,
-);
+const ginkoSocialCollection = {
+  prefix: "ginko-social",
+  width: 24,
+  height: 24,
+  icons: {
+    // Google Material Icons: https://github.com/material-icons/material-icons/blob/master/LICENSE
+    discord: {
+      body: '<path fill="currentColor" d="M19.27 5.33C17.94 4.71 16.5 4.26 15 4a.1.1 0 0 0-.07.03c-.18.33-.39.76-.53 1.09a16.1 16.1 0 0 0-4.8 0c-.14-.34-.35-.76-.54-1.09c-.01-.02-.04-.03-.07-.03c-1.5.26-2.93.71-4.27 1.33c-.01 0-.02.01-.03.02c-2.72 4.07-3.47 8.03-3.1 11.95c0 .02.01.04.03.05c1.8 1.32 3.53 2.12 5.24 2.65c.03.01.06 0 .07-.02c.4-.55.76-1.13 1.07-1.74c.02-.04 0-.08-.04-.09c-.57-.22-1.11-.48-1.64-.78c-.04-.02-.04-.08-.01-.11c.11-.08.22-.17.33-.25c.02-.02.05-.02.07-.01c3.44 1.57 7.15 1.57 10.55 0c.02-.01.05-.01.07.01c.11.09.22.17.33.26c.04.03.04.09-.01.11c-.52.31-1.07.56-1.64.78c-.04.01-.05.06-.04.09c.32.61.68 1.19 1.07 1.74c.03.01.06.02.09.01c1.72-.53 3.45-1.33 5.25-2.65c.02-.01.03-.03.03-.05c.44-4.53-.73-8.46-3.1-11.95c-.01-.01-.02-.02-.04-.02M8.52 14.91c-1.03 0-1.89-.95-1.89-2.12s.84-2.12 1.89-2.12c1.06 0 1.9.96 1.89 2.12c0 1.17-.84 2.12-1.89 2.12m6.97 0c-1.03 0-1.89-.95-1.89-2.12s.84-2.12 1.89-2.12c1.06 0 1.9.96 1.89 2.12c0 1.17-.83 2.12-1.89 2.12"/>',
+    },
+    // Material Design Icons: https://github.com/Templarian/MaterialDesign/blob/master/LICENSE
+    github: {
+      body: '<path fill="currentColor" d="M12 2A10 10 0 0 0 2 12c0 4.42 2.87 8.17 6.84 9.5c.5.08.66-.23.66-.5v-1.69c-2.77.6-3.36-1.34-3.36-1.34c-.46-1.16-1.11-1.47-1.11-1.47c-.91-.62.07-.6.07-.6c1 .07 1.53 1.03 1.53 1.03c.87 1.52 2.34 1.07 2.91.83c.09-.65.35-1.09.63-1.34c-2.22-.25-4.55-1.11-4.55-4.92c0-1.11.38-2 1.03-2.71c-.1-.25-.45-1.29.1-2.64c0 0 .84-.27 2.75 1.02c.79-.22 1.65-.33 2.5-.33s1.71.11 2.5.33c1.91-1.29 2.75-1.02 2.75-1.02c.55 1.35.2 2.39.1 2.64c.65.71 1.03 1.6 1.03 2.71c0 3.82-2.34 4.66-4.57 4.91c.36.31.69.92.69 1.85V21c0 .27.16.59.67.5C19.14 20.16 22 16.42 22 12A10 10 0 0 0 12 2"/>',
+    },
+  },
+} satisfies IconCollection;
+
+export const layerIconCollections = [
+  ...["circle-flags", "logos", "lucide"].map(
+    (prefix) => require(`@iconify-json/${prefix}/icons.json`) as IconCollection,
+  ),
+  ginkoSocialCollection,
+];

package/index.d.ts

@@ -29,6 +29,7 @@ declare module "nuxt/schema" {
 
   interface PublicRuntimeConfig {
     ginkoDocs?: {
+      primaryLocale?: "en" | "de";
       syntaxHighlighting?: GinkoDocsSyntaxHighlightingConfig;
     };
   }