@lupinum/ginko-docs 0.2.2

package/app/pages/blog/index.vue

@@ -0,0 +1,106 @@
+<script setup lang="ts">
+import { Badge } from "#ginko-docs/components/ui/badge";
+import { many } from "@lupinum/ginko-content/client";
+import { formatContentDate } from "#ginko-docs/utils/content";
+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";
+
+definePageMeta({ layout: "blog" });
+
+const { locale, t } = useI18n();
+const postsKey = computed(() => `blog-posts:${locale.value}`);
+const { data: posts } = await useAsyncData(
+  postsKey,
+  () =>
+    many("blog", {
+      locale: locale.value,
+      fallback: true,
+      populate: { author: "authors" },
+      sort: { date: "desc" },
+      limit: 50,
+    }),
+  { watch: [locale] },
+);
+const canonicalUrl = useCanonicalUrl();
+const config = useAppConfig().ginkoDocs;
+const siteName = computed(() => getLocalizedSiteText(config.site.name, locale.value));
+const fullTitle = computed(() => `${t("blog.pageTitle")} - ${siteName.value}`);
+
+useSeoMeta({
+  title: fullTitle,
+  description: computed(() => t("blog.description")),
+  ogTitle: fullTitle,
+  ogDescription: computed(() => t("blog.description")),
+  ogUrl: canonicalUrl,
+  twitterCard: "summary_large_image",
+});
+
+useHead(() => ({
+  link: [{ key: "canonical", rel: "canonical", href: canonicalUrl.value }],
+}));
+</script>
+
+<template>
+  <div class="mx-auto max-w-3xl">
+    <div class="mb-12">
+      <h1 class="text-3xl font-semibold tracking-tight text-foreground">{{ t("blog.title") }}</h1>
+      <p class="mt-2 text-muted-foreground">{{ t("blog.description") }}</p>
+    </div>
+
+    <div class="divide-y divide-border">
+      <article v-for="post in posts" :key="post.route.resolvedPath" class="group py-8">
+        <NuxtLink
+          :to="post.route.resolvedPath"
+          class="flex flex-col gap-6 sm:flex-row sm:items-start"
+        >
+          <div class="min-w-0 flex-1">
+            <div class="mb-3 flex items-center gap-2">
+              <Badge v-if="post.badge" variant="secondary" class="text-xs">{{ post.badge }}</Badge>
+              <span class="text-xs text-muted-foreground"
+                >{{ formatContentDate(post.date, locale)
+                }}<template v-if="post.readingTime"> · {{ post.readingTime }}</template></span
+              >
+            </div>
+            <div v-if="post.author" class="mb-3 flex items-center gap-2">
+              <img
+                v-if="post.author.avatar"
+                :src="post.author.avatar"
+                :alt="post.author.name"
+                class="size-5 shrink-0 rounded-full border border-border object-cover"
+                loading="lazy"
+              />
+              <p class="text-xs font-medium text-muted-foreground">
+                {{ post.author.name }} · {{ post.author.role }}
+              </p>
+            </div>
+            <h2
+              class="mb-2 text-xl font-semibold text-foreground transition-colors group-hover:text-primary"
+            >
+              {{ post.title }}
+            </h2>
+            <p class="text-sm leading-relaxed text-muted-foreground">{{ post.description }}</p>
+            <div class="mt-4 flex items-center gap-1 text-sm font-medium text-primary">
+              {{ t("blog.readMore") }}
+              <Icon
+                name="lucide:arrow-right"
+                class="size-4 transition-transform group-hover:translate-x-0.5"
+                aria-hidden="true"
+              />
+            </div>
+          </div>
+          <NuxtImg
+            v-if="post.image"
+            :src="post.image"
+            :alt="post.title"
+            class="aspect-[16/10] w-full shrink-0 rounded-lg border border-border object-cover sm:w-52"
+            width="416"
+            height="260"
+            loading="lazy"
+          />
+        </NuxtLink>
+      </article>
+    </div>
+  </div>
+</template>

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

@@ -0,0 +1,10 @@
+<script setup lang="ts">
+import DocsPageContent from "#ginko-docs/features/docs/components/DocsPageContent.vue";
+import { definePageMeta } from "#imports";
+
+definePageMeta({ layout: "docs" });
+</script>
+
+<template>
+  <DocsPageContent :key="$route.path" />
+</template>

package/app/pages/docs/index.vue

@@ -0,0 +1,23 @@
+<script setup lang="ts">
+import { definePageMeta, navigateTo, useRoute } from "#imports";
+import { useDocsEntryPath } from "#ginko-docs/features/docs/composables/useDocsEntryPath";
+
+definePageMeta({ layout: "docs" });
+
+const route = useRoute();
+const entryPath = await useDocsEntryPath();
+
+// Redirect the bare docs root to the first documentation page. Guard against
+// self-redirects when no docs pages exist (entry path falls back to the root).
+if (entryPath.value && entryPath.value !== route.path) {
+  await navigateTo(entryPath.value, { redirectCode: 302, replace: true });
+}
+</script>
+
+<template>
+  <main id="main-content" class="flex-1 px-4 py-12 md:px-6">
+    <NuxtLink v-if="entryPath && entryPath !== route.path" :to="entryPath" class="underline">
+      {{ entryPath }}
+    </NuxtLink>
+  </main>
+</template>

package/app/pages/index.vue

@@ -0,0 +1,140 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import { useI18n, useSeoMeta } from "#imports";
+import { getLocalizedSiteText } from "#ginko-docs/config/site.utils";
+import { useGinkoDocsConfig } from "#ginko-docs/composables/useGinkoDocsConfig";
+
+const config = useGinkoDocsConfig();
+const { locale } = useI18n();
+const localize = (value: string | { en: string; de?: string }) =>
+  getLocalizedSiteText(value, locale.value);
+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,
+  features: config.landing.features.map((feature) => ({
+    ...feature,
+    title: localize(feature.title),
+    description: localize(feature.description),
+  })),
+  heroMedia: config.landing.hero?.media,
+}));
+
+const heroCodeLines = computed(() =>
+  landing.value.heroMedia?.type === "code" ? landing.value.heroMedia.code.split("\n") : [],
+);
+
+useSeoMeta({
+  title: computed(() => localize(config.site.name)),
+  description: computed(() => localize(config.site.description)),
+});
+</script>
+
+<template>
+  <div class="overflow-hidden">
+    <section class="relative border-b border-border">
+      <div
+        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]'"
+          >
+            {{ landing.title }}
+          </h1>
+          <p class="mt-7 max-w-2xl text-lg leading-8 text-muted-foreground sm:text-xl">
+            {{ landing.description }}
+          </p>
+          <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"
+            >
+              {{ landing.primary.label }}
+              <Icon name="lucide:arrow-right" class="size-4" aria-hidden="true" />
+            </NuxtLink>
+            <NuxtLink
+              v-if="landing.secondary"
+              :to="landing.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.secondary.label }}
+            </NuxtLink>
+          </div>
+        </div>
+
+        <div v-if="landing.heroMedia" class="hidden w-[26rem] max-w-full shrink-0 lg:block">
+          <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"
+            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>
+        </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"
+      >
+        <article
+          v-for="feature in landing.features"
+          :key="feature.title"
+          class="min-w-0 md:px-9 md:first:pl-0 md:last:pr-0"
+        >
+          <Icon
+            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">
+            {{ feature.title }}
+          </h2>
+          <p class="mt-3 leading-7 text-muted-foreground">{{ feature.description }}</p>
+        </article>
+      </div>
+    </section>
+  </div>
+</template>

package/app/plugins/ssr-width.ts

@@ -0,0 +1,6 @@
+import { provideSSRWidth } from "@vueuse/core";
+import { defineNuxtPlugin } from "#imports";
+
+export default defineNuxtPlugin((nuxtApp) => {
+  provideSSRWidth(1024, nuxtApp.vueApp);
+});

package/app/utils/content.ts

@@ -0,0 +1,56 @@
+type TocLinkLike = {
+  id?: string;
+  text?: string;
+  label?: string;
+  depth?: number;
+  children?: TocLinkLike[];
+};
+
+export type FlatTocItem = {
+  id: string;
+  label: string;
+  depth?: number;
+};
+
+export function formatContentDate(
+  value?: string | Date | null,
+  locale: string = defaultLocale,
+): string {
+  if (!value) return "";
+
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) return "";
+
+  return new Intl.DateTimeFormat(locale, {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+  }).format(date);
+}
+
+export function flattenTocLinks(links?: TocLinkLike[] | null): FlatTocItem[] {
+  const output: FlatTocItem[] = [];
+
+  function visit(items: TocLinkLike[] | undefined) {
+    for (const item of items ?? []) {
+      const label = item.text ?? item.label;
+      if (item.id && label) {
+        output.push({
+          id: item.id,
+          label,
+          depth: item.depth,
+        });
+      }
+
+      visit(item.children);
+    }
+  }
+
+  visit(links ?? undefined);
+  return output;
+}
+
+export function filterTocByDepth(items: FlatTocItem[], maxDepth: number): FlatTocItem[] {
+  return items.filter((item) => (item.depth ?? 2) <= maxDepth);
+}
+import { defaultLocale } from "../../i18n/locales";

package/app/utils/index.ts

@@ -0,0 +1 @@
+export { cn } from "../../runtime/utils";

package/components.ts

@@ -0,0 +1,9 @@
+export {
+  contentComponentNames as ginkoDocsComponentNames,
+  contentComponentPolicy as ginkoDocsComponentPolicy,
+  contentComponentTags as ginkoDocsComponentTags,
+} from "./tags";
+export type {
+  ContentComponentName as GinkoDocsComponentName,
+  ContentComponentTag as GinkoDocsComponentTag,
+} from "./tags";

package/content.js

@@ -0,0 +1,175 @@
+import {
+  defineAgentAppPage,
+  defineAgentMetadataFields,
+  defineAgentSection,
+  defineCollection,
+  defineContentConfig,
+  reference,
+} from "@lupinum/ginko-content/config";
+import { z } from "zod";
+//#region layer/shared/route-slugs.ts
+const routeSlugs = {
+  home: {
+    en: "/",
+    de: "/",
+  },
+  docs: {
+    en: "/docs",
+    de: "/dokumentation",
+  },
+  blog: {
+    en: "/blog",
+    de: "/blog",
+  },
+};
+//#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 authorsSchema = z.object({
+  slug: z.string(),
+  name: z.string(),
+  role: z.string(),
+  bio: z.string(),
+  avatar: z.string(),
+  links: z
+    .array(
+      z.object({
+        label: z.string(),
+        href: z.string(),
+      }),
+    )
+    .optional(),
+});
+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]]));
+  const metadata = defineAgentMetadataFields([
+    "title",
+    "description",
+    "url",
+    "route",
+    "locale",
+    "section",
+    "collection",
+    "source",
+    "updated",
+  ]);
+  const docs = defineCollection({
+    type: "page",
+    source: i18n ? "{1.docs,1.dokumentation}/**/*.md" : "docs/**/*.md",
+    i18n: i18n ? true : void 0,
+    route: i18n ? routeMap("docs") : routeSlugs.docs[defaultLocale],
+    agent: {
+      section: "optional",
+      markdown: true,
+    },
+    strict: true,
+    schema: docsSchema,
+  });
+  const blog = defineCollection({
+    type: "page",
+    source: "2.blog/**/*.md",
+    i18n: i18n ? true : void 0,
+    route: i18n ? routeMap("blog") : routeSlugs.blog[defaultLocale],
+    agent: {
+      section: "blog",
+      markdown: true,
+    },
+    strict: true,
+    schema: blogSchema,
+  });
+  const authors = defineCollection({
+    type: "data",
+    source: "authors/**/*.json",
+    i18n: i18n ? true : void 0,
+    strict: true,
+    sitemap: false,
+    schema: authorsSchema,
+  });
+  const config = {
+    agent: {
+      site: {
+        title: options.site.name,
+        description: options.site.description,
+        url: options.site.url,
+      },
+      markdown: {
+        metadata: {
+          enabled: true,
+          defaultFields: metadata,
+        },
+      },
+      sections: [
+        ...(options.blog
+          ? [
+              defineAgentSection({
+                id: "blog",
+                title: "Blog",
+                order: 40,
+              }),
+            ]
+          : []),
+        defineAgentSection({
+          id: "optional",
+          title: "Documentation",
+          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)
+    return defineContentConfig({
+      ...config,
+      collections: {
+        docs,
+        blog,
+        authors,
+      },
+    });
+  return defineContentConfig({
+    ...config,
+    collections: { docs },
+  });
+}
+//#endregion
+export { defineGinkoDocsConfig };

package/content.ts

@@ -0,0 +1,148 @@
+import {
+  defineAgentAppPage,
+  defineAgentMetadataFields,
+  defineAgentSection,
+  defineCollection,
+  defineContentConfig,
+  reference,
+} from "@lupinum/ginko-content/config";
+import type { ContentCollectionConfig, ContentConfig } from "@lupinum/ginko-content/config";
+import { z } from "zod";
+import { routeSlugs } from "./shared/route-slugs";
+
+export interface GinkoDocsContentOptions {
+  site: { name: string; description: string; url: string };
+  locales?: Array<"en" | "de">;
+  defaultLocale?: "en" | "de";
+  blog?: boolean;
+}
+
+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 authorsSchema = z.object({
+  slug: z.string(),
+  name: z.string(),
+  role: z.string(),
+  bio: z.string(),
+  avatar: z.string(),
+  links: z.array(z.object({ label: z.string(), href: z.string() })).optional(),
+});
+
+type DocsCollection = ContentCollectionConfig<typeof docsSchema>;
+type BlogCollection = ContentCollectionConfig<typeof blogSchema>;
+type AuthorsCollection = ContentCollectionConfig<typeof authorsSchema>;
+type DocsContentConfig = ContentConfig<{ docs: DocsCollection }>;
+type DocsBlogContentConfig = ContentConfig<{
+  docs: DocsCollection;
+  blog: BlogCollection;
+  authors: AuthorsCollection;
+}>;
+
+export function defineGinkoDocsConfig(
+  options: GinkoDocsContentOptions & { blog: true },
+): DocsBlogContentConfig;
+export function defineGinkoDocsConfig(options: GinkoDocsContentOptions): DocsContentConfig;
+export function defineGinkoDocsConfig(
+  options: GinkoDocsContentOptions,
+): DocsContentConfig | DocsBlogContentConfig {
+  const locales = options.locales ?? ["en"];
+  const defaultLocale = options.defaultLocale ?? locales[0] ?? "en";
+  const i18n = locales.length > 1;
+  const routeMap = (key: "docs" | "blog") =>
+    Object.fromEntries(locales.map((locale) => [locale, routeSlugs[key][locale]]));
+  const metadata = defineAgentMetadataFields([
+    "title",
+    "description",
+    "url",
+    "route",
+    "locale",
+    "section",
+    "collection",
+    "source",
+    "updated",
+  ]);
+  const docs = defineCollection({
+    type: "page",
+    source: i18n ? "{1.docs,1.dokumentation}/**/*.md" : "docs/**/*.md",
+    i18n: i18n ? true : undefined,
+    route: i18n ? routeMap("docs") : routeSlugs.docs[defaultLocale],
+    agent: { section: "optional", markdown: true },
+    strict: true,
+    schema: docsSchema,
+  });
+  const blog = defineCollection({
+    type: "page",
+    source: "2.blog/**/*.md",
+    i18n: i18n ? true : undefined,
+    route: i18n ? routeMap("blog") : routeSlugs.blog[defaultLocale],
+    agent: { section: "blog", markdown: true },
+    strict: true,
+    schema: blogSchema,
+  });
+  const authors = defineCollection({
+    type: "data",
+    source: "authors/**/*.json",
+    i18n: i18n ? true : undefined,
+    strict: true,
+    sitemap: false,
+    schema: authorsSchema,
+  });
+  const config = {
+    agent: {
+      site: {
+        title: options.site.name,
+        description: options.site.description,
+        url: options.site.url,
+      },
+      markdown: { metadata: { enabled: true, defaultFields: metadata } },
+      sections: [
+        ...(options.blog ? [defineAgentSection({ id: "blog", title: "Blog", order: 40 })] : []),
+        defineAgentSection({ id: "optional", title: "Documentation", 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) {
+    return defineContentConfig({
+      ...config,
+      collections: { docs, blog, authors },
+    }) as DocsBlogContentConfig;
+  }
+  return defineContentConfig({ ...config, collections: { docs } }) as DocsContentConfig;
+}

package/i18n/i18n.config.ts

@@ -0,0 +1,10 @@
+import { defaultLocale } from "./locales";
+import { messages } from "./messages/index";
+import { defineI18nConfig } from "#imports";
+
+export default defineI18nConfig(() => ({
+  legacy: false,
+  locale: defaultLocale,
+  fallbackLocale: defaultLocale,
+  messages,
+}));