@lupinum/ginko-docs 0.2.5 → 0.3.0-rc.2

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.5 <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.5
+pnpm add -D @lupinum/ginko-docs@0.3.0-rc.2 @lupinum/ginko-content@0.4.0-rc.1
 ```
 
 Keep the public identity in one shared value:

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/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/content-collections.ts

@@ -0,0 +1,85 @@
+import { defineCollection, defineContentConfig, reference } from "@lupinum/ginko-content/config";
+import { z } from "zod";
+import { routeSlugs } from "./shared/route-slugs";
+
+const isoDate = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Expected an ISO date (YYYY-MM-DD)");
+const nonEmptyString = z.string().trim().min(1);
+const redirectFrom = z
+  .array(nonEmptyString.regex(/^\//, "redirectFrom entries must be absolute site paths"))
+  .optional();
+
+const withSitemapLastmod = <T extends object>(data: T, lastmod: string | undefined) =>
+  lastmod ? { ...data, sitemap: { lastmod: `${lastmod}T00:00:00.000Z` } } : data;
+
+const docsSchema = 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(),
+});
+const docsSchemaWithLastmod = docsSchema.transform((data) =>
+  withSitemapLastmod(data, data.updated),
+);
+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(),
+  redirectFrom,
+});
+const blogSchemaWithLastmod = blogSchema.transform((data) => withSitemapLastmod(data, data.date));
+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(),
+});
+
+export function createGinkoDocsCollections(i18n: boolean) {
+  return defineContentConfig({
+    collections: {
+      docs: defineCollection({
+        type: "page",
+        source: i18n ? "{1.docs,1.dokumentation}/**/*.md" : "docs/**/*.md",
+        i18n: i18n ? true : undefined,
+        route: i18n ? routeSlugs.docs : routeSlugs.docs.en,
+        agent: { section: "optional", markdown: true },
+        strict: true,
+        schema: docsSchemaWithLastmod,
+      }),
+      blog: defineCollection({
+        type: "page",
+        source: "2.blog/*.md",
+        i18n: i18n ? true : undefined,
+        route: i18n ? routeSlugs.blog : routeSlugs.blog.en,
+        agent: { section: "blog", markdown: true },
+        strict: true,
+        schema: blogSchemaWithLastmod,
+      }),
+      authors: defineCollection({
+        type: "data",
+        source: "authors/**/*.json",
+        i18n: i18n ? true : undefined,
+        strict: true,
+        sitemap: false,
+        schema: authorsSchema,
+      }),
+    },
+  }).collections;
+}

package/content.js

@@ -22,17 +22,12 @@ const routeSlugs = {
   },
 };
 //#endregion
-//#region layer/content.ts
+//#region layer/content-collections.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);
-/** 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
     ? {
@@ -86,6 +81,46 @@ const authorsSchema = z.object({
     )
     .optional(),
 });
+function createGinkoDocsCollections(i18n) {
+  return defineContentConfig({
+    collections: {
+      docs: defineCollection({
+        type: "page",
+        source: i18n ? "{1.docs,1.dokumentation}/**/*.md" : "docs/**/*.md",
+        i18n: i18n ? true : void 0,
+        route: i18n ? routeSlugs.docs : routeSlugs.docs.en,
+        agent: {
+          section: "optional",
+          markdown: true,
+        },
+        strict: true,
+        schema: docsSchemaWithLastmod,
+      }),
+      blog: defineCollection({
+        type: "page",
+        source: "2.blog/*.md",
+        i18n: i18n ? true : void 0,
+        route: i18n ? routeSlugs.blog : routeSlugs.blog.en,
+        agent: {
+          section: "blog",
+          markdown: true,
+        },
+        strict: true,
+        schema: blogSchemaWithLastmod,
+      }),
+      authors: defineCollection({
+        type: "data",
+        source: "authors/**/*.json",
+        i18n: i18n ? true : void 0,
+        strict: true,
+        sitemap: false,
+        schema: authorsSchema,
+      }),
+    },
+  }).collections;
+}
+//#endregion
+//#region layer/content.ts
 function defineGinkoDocsConfig(options) {
   const locales = options.locales ?? ["en"];
   if (
@@ -106,38 +141,7 @@ function defineGinkoDocsConfig(options) {
     "source",
     "updated",
   ]);
-  const docs = defineCollection({
-    type: "page",
-    source: i18n ? "{1.docs,1.dokumentation}/**/*.md" : "docs/**/*.md",
-    i18n: i18n ? true : void 0,
-    route: i18n ? routeSlugs.docs : routeSlugs.docs.en,
-    agent: {
-      section: "optional",
-      markdown: true,
-    },
-    strict: true,
-    schema: docsSchemaWithLastmod,
-  });
-  const blog = defineCollection({
-    type: "page",
-    source: "2.blog/*.md",
-    i18n: i18n ? true : void 0,
-    route: i18n ? routeSlugs.blog : routeSlugs.blog.en,
-    agent: {
-      section: "blog",
-      markdown: true,
-    },
-    strict: true,
-    schema: blogSchemaWithLastmod,
-  });
-  const authors = defineCollection({
-    type: "data",
-    source: "authors/**/*.json",
-    i18n: i18n ? true : void 0,
-    strict: true,
-    sitemap: false,
-    schema: authorsSchema,
-  });
+  const { docs, blog, authors } = createGinkoDocsCollections(i18n);
   const config = {
     agent: {
       site: {

package/content.ts

@@ -1,27 +1,10 @@
 import {
   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";
-
-const isoDate = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Expected an ISO date (YYYY-MM-DD)");
-const nonEmptyString = z.string().trim().min(1);
-/** Former public URLs of a page, as served: locale prefix and translated slugs included. */
-const redirectFrom = z
-  .array(nonEmptyString.regex(/^\//, "redirectFrom entries must be absolute site paths"))
-  .optional();
-
-/**
- * Derives the sitemap lastmod from the authored date so it has one source of
- * truth. Route records require normalized UTC ISO values.
- */
-const withSitemapLastmod = <T extends object>(data: T, lastmod: string | undefined) =>
-  lastmod ? { ...data, sitemap: { lastmod: `${lastmod}T00:00:00.000Z` } } : data;
+import type { ContentConfig } from "@lupinum/ginko-content/config";
+import { createGinkoDocsCollections } from "./content-collections";
 
 export interface GinkoDocsContentOptions {
   site: {
@@ -33,49 +16,10 @@ export interface GinkoDocsContentOptions {
   blog?: boolean;
 }
 
-const docsSchema = 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(),
-});
-const docsSchemaWithLastmod = docsSchema.transform((data) =>
-  withSitemapLastmod(data, data.updated),
-);
-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(),
-  redirectFrom,
-});
-const blogSchemaWithLastmod = blogSchema.transform((data) => withSitemapLastmod(data, data.date));
-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 docsSchemaWithLastmod>;
-type BlogCollection = ContentCollectionConfig<typeof blogSchemaWithLastmod>;
-type AuthorsCollection = ContentCollectionConfig<typeof authorsSchema>;
+type Collections = ReturnType<typeof createGinkoDocsCollections>;
+type DocsCollection = Collections["docs"];
+type BlogCollection = Collections["blog"];
+type AuthorsCollection = Collections["authors"];
 type DocsContentConfig = ContentConfig<{ docs: DocsCollection }>;
 type DocsBlogContentConfig = ContentConfig<{
   docs: DocsCollection;
@@ -110,32 +54,7 @@ export function defineGinkoDocsConfig(
     "source",
     "updated",
   ]);
-  const docs = defineCollection({
-    type: "page",
-    source: i18n ? "{1.docs,1.dokumentation}/**/*.md" : "docs/**/*.md",
-    i18n: i18n ? true : undefined,
-    route: i18n ? routeSlugs.docs : routeSlugs.docs.en,
-    agent: { section: "optional", markdown: true },
-    strict: true,
-    schema: docsSchemaWithLastmod,
-  });
-  const blog = defineCollection({
-    type: "page",
-    source: "2.blog/*.md",
-    i18n: i18n ? true : undefined,
-    route: i18n ? routeSlugs.blog : routeSlugs.blog.en,
-    agent: { section: "blog", markdown: true },
-    strict: true,
-    schema: blogSchemaWithLastmod,
-  });
-  const authors = defineCollection({
-    type: "data",
-    source: "authors/**/*.json",
-    i18n: i18n ? true : undefined,
-    strict: true,
-    sitemap: false,
-    schema: authorsSchema,
-  });
+  const { docs, blog, authors } = createGinkoDocsCollections(i18n);
   const config = {
     agent: {
       site: {

package/nuxt.config.ts

@@ -43,7 +43,7 @@ export default defineNuxtConfig({
   },
   mcp: {
     name: "Ginko Docs",
-    version: "0.2.5",
+    version: "0.3.0-rc.2",
   },
   components: {
     dirs: [
@@ -127,7 +127,7 @@ export default defineNuxtConfig({
     markdown: {
       plugins: [
         [
-          "highlight",
+          "shiki",
           {
             preStyles: false,
             transformers: [transformerNotationDiff(), transformerNotationHighlight()],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lupinum/ginko-docs",
-  "version": "0.2.5",
+  "version": "0.3.0-rc.2",
   "description": "A Nuxt documentation layer powered by Ginko Content.",
   "keywords": [
     "content",
@@ -9,14 +9,14 @@
     "markdown",
     "nuxt"
   ],
-  "homepage": "https://github.com/Mat4m0/lupinum-docs-shadcn#readme",
+  "homepage": "https://ginko-docs.lupinum.com",
   "bugs": {
-    "url": "https://github.com/Mat4m0/lupinum-docs-shadcn/issues"
+    "url": "https://github.com/lupinum-dev/ginko-docs/issues"
   },
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Mat4m0/lupinum-docs-shadcn.git",
+    "url": "git+https://github.com/lupinum-dev/ginko-docs.git",
     "directory": "layer"
   },
   "files": [
@@ -26,6 +26,7 @@
     "runtime",
     "server",
     "shared",
+    "content-collections.ts",
     "content.js",
     "content.ts",
     "components.ts",
@@ -72,9 +73,9 @@
     "clsx": "^2.1.1",
     "motion-v": "^2.3.0",
     "nitropack": "^2.13.4",
-    "nuxt-og-image": "^6.7.7",
+    "nuxt-og-image": "^6.7.8",
     "reka-ui": "^2.10.3",
-    "satori": "^0.29.0",
+    "satori": "^0.19.3",
     "shiki": "^4.4.3",
     "tailwind-merge": "^3.6.0",
     "tailwindcss": "^4.3.3",
@@ -82,7 +83,7 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@lupinum/ginko-content": ">=0.3.5 <0.4.0",
+    "@lupinum/ginko-content": ">=0.4.0-rc.1 <0.5.0",
     "nuxt": ">=4.4.7 <5",
     "vue": "^3.5.35",
     "vue-router": "^5.1.0"

package/server/utils/blog-feed.ts

@@ -6,9 +6,11 @@ import { blog } from "../../i18n/messages/global/blog";
 import { locales, localizedPath, type LocaleCode } from "../../i18n/locales";
 import { routeSlugs } from "../../shared/route-slugs";
 import { getLocalizedSiteText } from "../../app/config/site.utils";
+import { createGinkoDocsCollections } from "../../content-collections";
 import { buildRssFeed } from "./feed";
 
 export const MAX_FEED_POSTS = 50;
+const { blog: blogCollection, authors: authorsCollection } = createGinkoDocsCollections(true);
 
 export function blogFeedPath(locale: LocaleCode): string {
   return `${localizedPath(locale, routeSlugs.blog[locale])}/rss.xml`;
@@ -23,10 +25,10 @@ export async function serveBlogFeed(event: H3Event, locale: LocaleCode) {
   }
 
   const site = useAppConfig().ginkoDocs.site;
-  const posts = await many(event, "blog", {
+  const posts = await many(event, blogCollection, {
     locale,
     fallback: true,
-    populate: { author: "authors" },
+    populate: { author: authorsCollection },
     sort: { date: "desc" },
     limit: MAX_FEED_POSTS,
   });

package/shared/types/app-config.ts

@@ -58,17 +58,6 @@ export type GinkoDocsHeroMedia =
   | { type: "code"; code: string; language?: string; filename?: string }
   | { type: "code-tabs"; tabs: GinkoDocsHeroCodeTab[] };
 
-export type GinkoDocsPlausibleExtension =
-  | "hash"
-  | "outbound-links"
-  | "file-downloads"
-  | "tagged-events"
-  | "revenue"
-  | "pageview-props"
-  | "compat"
-  | "local"
-  | "manual";
-
 export interface GinkoDocsAppConfig {
   theme: {
     neutral: GinkoDocsNeutralPalette;
@@ -99,12 +88,8 @@ export interface GinkoDocsAppConfig {
   };
   analytics?: {
     plausible?: {
-      /** Leave unset to keep analytics fully disabled. */
-      domain?: string;
-      /** Self-hosted Plausible script URL override. */
-      scriptSrc?: string;
-      /** Plausible script extensions, e.g. ["outbound-links", "file-downloads"]. */
-      extensions?: GinkoDocsPlausibleExtension[];
+      /** Public site-specific ID from the Plausible pa-<id>.js script URL. */
+      scriptId?: string;
     };
   };
   social: Partial<Record<GinkoDocsSocialPlatform, GinkoDocsSocialEntry>>;