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

package/README.md

@@ -29,7 +29,7 @@ Use this package when a Nuxt application needs documentation routes, navigation,
 ## Installation
 
 ```bash
-pnpm add -D @lupinum/ginko-docs@0.3.0 @lupinum/ginko-content@0.4.0-rc.2
+pnpm add -D @lupinum/ginko-docs@0.4.0-rc.2 @lupinum/ginko-content@1.0.0-beta.5
 ```
 
 ```ts
@@ -49,7 +49,7 @@ export default defineGinkoDocsConfig({
   site: {
     name: "Example Docs",
     description: "Documentation for Example.",
-    url: "https://docs.example.com",
+    whenToUse: "Use this site to learn and operate Example.",
   },
   locales: ["en"],
   blog: false,

package/app/app.vue

@@ -18,6 +18,7 @@ const siteUrl = docsConfig.site.url;
 
 useSeoMeta({
   ogSiteName: computed(() => getLocalizedSiteText(docsConfig.site.name, locale.value)),
+  ogType: "website",
   ogUrl: canonicalUrl,
   twitterCard: "summary_large_image",
 });
@@ -35,6 +36,15 @@ useSchemaJsonLd(() => [
     url: siteUrl,
     inLanguage: locale.value,
   },
+  {
+    "@type": "SoftwareApplication",
+    name: getLocalizedSiteText(docsConfig.site.name, locale.value),
+    description: getLocalizedSiteText(docsConfig.site.description, locale.value),
+    url: siteUrl,
+    applicationCategory: "DeveloperApplication",
+    operatingSystem: "Web",
+    ...(docsConfig.social?.github ? { sameAs: [docsConfig.social.github] } : {}),
+  },
 ]);
 
 useHead(() => ({

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,7 +52,10 @@ const authorsSchema = z.object({
   links: z.array(z.object({ label: z.string(), href: z.string() })).optional(),
 });
 
-export function createGinkoDocsCollections(i18n: boolean) {
+export function createGinkoDocsCollections(
+  i18n: boolean,
+  docsMarkdown: ContentAgentCollectionConfig["markdown"] = true,
+) {
   return defineContentConfig({
     collections: {
       docs: defineCollection({
@@ -59,7 +63,7 @@ export function createGinkoDocsCollections(i18n: boolean) {
         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 },
+        agent: { section: "optional", markdown: docsMarkdown },
         strict: true,
         schema: docsSchemaWithLastmod,
       }),

package/content.js

@@ -81,7 +81,7 @@ const authorsSchema = z.object({
     )
     .optional(),
 });
-function createGinkoDocsCollections(i18n) {
+function createGinkoDocsCollections(i18n, docsMarkdown = true) {
   return defineContentConfig({
     collections: {
       docs: defineCollection({
@@ -91,7 +91,7 @@ function createGinkoDocsCollections(i18n) {
         route: i18n ? routeSlugs.docs : routeSlugs.docs.en,
         agent: {
           section: "optional",
-          markdown: true,
+          markdown: docsMarkdown,
         },
         strict: true,
         schema: docsSchemaWithLastmod,
@@ -141,13 +141,14 @@ function defineGinkoDocsConfig(options) {
     "source",
     "updated",
   ]);
-  const { docs, blog, authors } = createGinkoDocsCollections(i18n);
+  const { docs, blog, authors } = createGinkoDocsCollections(i18n, 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 +157,7 @@ function defineGinkoDocsConfig(options) {
         },
       },
       sections: [
+        ...(options.agent?.sections ?? []),
         ...(options.blog
           ? [
               defineAgentSection({
@@ -177,6 +179,7 @@ function defineGinkoDocsConfig(options) {
           order: 100,
         }),
       ],
+      ...(options.agent?.pages ? { pages: [...options.agent.pages] } : {}),
     },
   };
   if (options.blog)

package/content.ts

@@ -1,17 +1,32 @@
 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 };
   };
+  agent?: GinkoDocsAgentOptions;
   locales?: readonly ["en"] | readonly ["en", "de"];
   blog?: boolean;
 }
@@ -54,16 +69,18 @@ export function defineGinkoDocsConfig(
     "source",
     "updated",
   ]);
-  const { docs, blog, authors } = createGinkoDocsCollections(i18n);
+  const { docs, blog, authors } = createGinkoDocsCollections(i18n, 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 +90,7 @@ export function defineGinkoDocsConfig(
           order: 100,
         }),
       ],
+      ...(options.agent?.pages ? { pages: [...options.agent.pages] } : {}),
     },
   };
 

package/nuxt.config.ts

@@ -10,6 +10,7 @@ import { i18nPages } from "./i18n/routes";
 import { defaultLocale, localeCodes, locales, localizedPath } from "./i18n/locales";
 import { routeSlugs } from "./shared/route-slugs";
 import { layerIconCollections, layerIconNames } from "./icon-bundle";
+import packageMetadata from "./package.json" with { type: "json" };
 
 const root = dirname(fileURLToPath(import.meta.url));
 const app = join(root, "app");
@@ -56,7 +57,7 @@ export default defineNuxtConfig({
   },
   mcp: {
     name: "Ginko Docs",
-    version: "0.3.0",
+    version: packageMetadata.version,
   },
   components: {
     dirs: [
@@ -163,7 +164,7 @@ export default defineNuxtConfig({
     },
     search: { engine: "minisearch" },
     sitemap: true,
-    agent: { routes: true, linkHeaders: true, markdownNegotiation: true, prerender: true },
+    agent: { routes: true, linkHeaders: true, delivery: "static" },
   },
   sitemap: {
     excludeAppSources: ["nuxt:prerender"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lupinum/ginko-docs",
-  "version": "0.3.0",
+  "version": "0.4.0-rc.2",
   "description": "A Nuxt documentation layer powered by Ginko Content.",
   "keywords": [
     "content",
@@ -86,7 +86,7 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@lupinum/ginko-content": ">=0.4.0-rc.2 <0.5.0",
+    "@lupinum/ginko-content": ">=1.0.0-beta.5 <2.0.0",
     "nuxt": ">=4.5.1 <5",
     "vue": "^3.5.35",
     "vue-router": "^5.1.0"

package/server/plugins/sitemap-policy.ts

@@ -0,0 +1,12 @@
+import { defineNitroPlugin } from "nitropack/runtime/plugin";
+import { filterSitemapEntries } from "../utils/sitemap";
+
+export default defineNitroPlugin((nitro) => {
+  nitro.hooks.hook("sitemap:resolved", (context) => {
+    const content = useRuntimeConfig(context.event).content;
+    context.urls = filterSitemapEntries(context.urls, {
+      locales: content.locales,
+      blogEnabled: Boolean(content.collections.blog),
+    });
+  });
+});

package/server/routes/.well-known/ai-catalog.json.get.ts

@@ -0,0 +1,13 @@
+import { setResponseHeaders } from "h3";
+import { useAppConfig } from "#imports";
+import { createGinkoDocsAiCatalog } from "../../utils/mcp-server-card";
+
+export default defineEventHandler((event) => {
+  setResponseHeaders(event, {
+    "access-control-allow-origin": "*",
+    "cache-control": "public, max-age=3600",
+    "content-type": "application/ai-catalog+json; charset=utf-8",
+  });
+
+  return createGinkoDocsAiCatalog(useAppConfig().ginkoDocs.site.url);
+});

package/server/routes/mcp/server-card.get.ts

@@ -0,0 +1,17 @@
+import { setResponseHeaders } from "h3";
+import { useAppConfig } from "#imports";
+import packageMetadata from "../../../package.json" with { type: "json" };
+import { createGinkoDocsServerCard } from "../../utils/mcp-server-card";
+
+export default defineEventHandler((event) => {
+  setResponseHeaders(event, {
+    "access-control-allow-origin": "*",
+    "cache-control": "public, max-age=3600",
+    "content-type": "application/mcp-server-card+json; charset=utf-8",
+  });
+
+  return createGinkoDocsServerCard({
+    origin: useAppConfig().ginkoDocs.site.url,
+    version: packageMetadata.version,
+  });
+});

package/server/utils/mcp-server-card.ts

@@ -0,0 +1,45 @@
+export interface GinkoDocsServerCardOptions {
+  origin: string;
+  version: string;
+}
+
+export function createGinkoDocsServerCard({ origin, version }: GinkoDocsServerCardOptions) {
+  const baseUrl = new URL(origin);
+
+  return {
+    $schema: "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
+    name: "dev.lupinum/ginko-docs",
+    title: "Ginko Docs",
+    version,
+    description: "Read published Ginko Docs pages through its public MCP tools.",
+    websiteUrl: new URL("/docs/features/agent-readable-output", baseUrl).toString(),
+    repository: {
+      source: "github",
+      url: "https://github.com/lupinum-dev/ginko-docs",
+    },
+    remotes: [
+      {
+        type: "streamable-http",
+        url: new URL("/mcp", baseUrl).toString(),
+        supportedProtocolVersions: ["2025-11-25"],
+      },
+    ],
+  } as const;
+}
+
+export function createGinkoDocsAiCatalog(origin: string) {
+  const baseUrl = new URL(origin);
+
+  return {
+    specVersion: "1.0",
+    entries: [
+      {
+        identifier: "urn:air:ginko-docs.lupinum.com:mcp:ginko-docs",
+        displayName: "Ginko Docs MCP Server",
+        type: "application/mcp-server-card+json",
+        description: "Read the public Ginko Docs documentation through MCP.",
+        url: new URL("/mcp/server-card", baseUrl).toString(),
+      },
+    ],
+  } as const;
+}

package/server/utils/sitemap.ts

@@ -0,0 +1,45 @@
+import { localeCodes, localizedPath } from "../../i18n/locales";
+import { routeSlugs } from "../../shared/route-slugs";
+
+interface SitemapAlternative {
+  href: string;
+}
+
+export interface SitemapEntry {
+  loc: string;
+  alternatives?: SitemapAlternative[];
+}
+
+interface SitemapContentPolicy {
+  locales: readonly string[];
+  blogEnabled: boolean;
+}
+
+const pathname = (url: string) => new URL(url, "https://ginko.invalid").pathname;
+
+export function filterSitemapEntries<Entry extends SitemapEntry>(
+  entries: Entry[],
+  policy: SitemapContentPolicy,
+): Entry[] {
+  const disabledLocaleRoots = localeCodes
+    .filter((locale) => !policy.locales.includes(locale))
+    .map((locale) => `/${locale}`);
+  const disabledBlogRoots = policy.blogEnabled
+    ? []
+    : localeCodes.map((locale) => localizedPath(locale, routeSlugs.blog[locale]));
+  const excludedRoots = [...disabledLocaleRoots, ...disabledBlogRoots];
+  const isExcluded = (url: string) => {
+    const path = pathname(url);
+    return excludedRoots.some((root) => path === root || path.startsWith(`${root}/`));
+  };
+
+  return entries
+    .filter((entry) => !isExcluded(entry.loc))
+    .map((entry) => {
+      if (!entry.alternatives) return entry;
+      return {
+        ...entry,
+        alternatives: entry.alternatives.filter((alternative) => !isExcluded(alternative.href)),
+      };
+    });
+}