@lupinum/ginko-docs 0.2.2

package/nuxt.config.ts

@@ -0,0 +1,194 @@
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import tailwindcss from "@tailwindcss/vite";
+import { transformerNotationDiff, transformerNotationHighlight } from "@shikijs/transformers";
+import darkPlus from "shiki/dist/themes/dark-plus.mjs";
+import lightPlus from "shiki/dist/themes/light-plus.mjs";
+import { contentComponentPolicy, contentComponentTags } from "./tags";
+import { i18nPages } from "./i18n/routes";
+import { includeIconNames, layerIconCollections, layerIconNames } from "./icon-bundle";
+
+const root = dirname(fileURLToPath(import.meta.url));
+const app = join(root, "app");
+
+export default defineNuxtConfig({
+  build: {
+    transpile: ["@lupinum/ginko-docs"],
+  },
+  $meta: { name: "ginko-docs" },
+  compatibilityDate: "2025-07-15",
+  alias: { "#ginko-docs": app },
+  css: [join(app, "assets/css/tailwind.css"), join(app, "assets/css/prose.css")],
+  modules: [
+    join(root, "modules/feature-routing"),
+    "@nuxt/icon",
+    "@nuxt/fonts",
+    "@nuxtjs/i18n",
+    "@lupinum/ginko-content",
+    "@nuxt/image",
+    "@nuxt/scripts",
+    "nuxt-og-image",
+    "@nuxtjs/sitemap",
+    "@nuxtjs/robots",
+    "@nuxtjs/color-mode",
+    "@nuxtjs/mcp-toolkit",
+  ],
+  ogImage: {
+    zeroRuntime: true,
+    // Satori renders queue up behind page prerendering on modest build
+    // machines; the default 15s budget is too tight under that contention.
+    security: { renderTimeout: 120_000 },
+  },
+  mcp: {
+    name: "Ginko Docs",
+    version: "0.2.2",
+  },
+  components: {
+    dirs: [
+      {
+        path: join(app, "components/site"),
+        pathPrefix: false,
+        global: true,
+        pattern: [
+          "SiteBanner.vue",
+          "SiteFooter.vue",
+          "SiteHeader.vue",
+          "SiteInteractionLayer.vue",
+          "SiteLocaleSwitcher.vue",
+          "SiteLogoMark.vue",
+          "SiteSkipLink.vue",
+        ],
+      },
+      {
+        path: join(app, "features/docs/components"),
+        pathPrefix: false,
+        global: true,
+        pattern: "DocsSidebar.vue",
+      },
+      { path: join(app, "components/mdc"), pathPrefix: false, global: true },
+      { path: join(app, "components/prose"), pathPrefix: false, global: true },
+    ],
+  },
+  imports: { autoImport: false },
+  colorMode: { classSuffix: "" },
+  icon: {
+    provider: "none",
+    fallbackToApi: false,
+    customCollections: layerIconCollections,
+    clientBundle: {
+      icons: [...layerIconNames],
+      includeCustomCollections: false,
+      scan: {
+        globInclude: [
+          "**/*.{vue,js,mjs,cjs,ts,jsx,tsx,md,mdc,mdx,yml,yaml}",
+          "**/.navigation.{yml,yaml}",
+        ],
+        globExclude: [
+          ".git",
+          ".nuxt",
+          ".output",
+          ".cache",
+          "node_modules",
+          "dist",
+          "build",
+          "coverage",
+          "test",
+          "tests",
+        ],
+      },
+    },
+  },
+  fonts: {
+    defaults: {
+      weights: [400, 500, 600, 700],
+      styles: ["normal"],
+      subsets: ["latin", "latin-ext"],
+    },
+    families: [{ name: "Public Sans", provider: "google", global: true }],
+  },
+  i18n: {
+    customRoutes: "config",
+    defaultLocale: "en",
+    detectBrowserLanguage: false,
+    pages: i18nPages,
+    strategy: "prefix_except_default",
+    vueI18n: join(root, "i18n/i18n.config.ts"),
+  },
+  content: {
+    componentPolicy: contentComponentPolicy,
+    i18n: {
+      translatedSlugs: true,
+    },
+    markdown: {
+      plugins: [
+        [
+          "highlight",
+          {
+            preStyles: false,
+            transformers: [transformerNotationDiff(), transformerNotationHighlight()],
+            themes: { light: lightPlus, dark: darkPlus },
+          },
+        ],
+        ["toc", { depth: 4, searchDepth: 4 }],
+        "summary",
+        ["footnotes", { label: "" }],
+      ],
+      tags: contentComponentTags,
+      anchorLinks: { depth: 4, exclude: [1] },
+    },
+    search: { engine: "minisearch" },
+    sitemap: true,
+    agent: { routes: true, linkHeaders: true, markdownNegotiation: true, prerender: true },
+  },
+  sitemap: {
+    excludeAppSources: ["nuxt:prerender"],
+  },
+  app: {
+    head: {
+      charset: "utf-8",
+      htmlAttrs: { lang: "en" },
+      viewport: "width=device-width, initial-scale=1",
+      meta: [{ name: "color-scheme", content: "light dark" }],
+    },
+  },
+  hooks: {
+    "icon:clientBundleIcons"(icons) {
+      includeIconNames(icons);
+    },
+    "components:dirs"(dirs) {
+      const defaultComponentsDir = join(app, "components").replaceAll("\\", "/");
+      const filtered = dirs.filter((entry) => {
+        const path = (typeof entry === "string" ? entry : entry.path).replaceAll("\\", "/");
+        return path !== defaultComponentsDir;
+      });
+      dirs.splice(0, dirs.length, ...filtered);
+    },
+  },
+  nitro: {
+    prerender: {
+      // OG images render through a Resvg worker. Parallel prerenders can
+      // terminate that worker under load and leave otherwise valid pages with
+      // 408/500 social-image routes, so package builds must stay serialized.
+      concurrency: 1,
+      crawlLinks: true,
+      failOnError: true,
+      routes: ["/llms.txt", "/llms-full.txt", "/sitemap.xml", "/robots.txt"],
+    },
+  },
+  vite: {
+    optimizeDeps: {
+      include: [
+        "@vueuse/core",
+        "class-variance-authority",
+        "clsx",
+        "reka-ui",
+        "tailwind-merge",
+        "zod",
+      ],
+    },
+    resolve: {
+      dedupe: ["@lupinum/ginko-content", "vue", "vue-router"],
+    },
+    plugins: [tailwindcss()],
+  },
+});

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@lupinum/ginko-docs",
+  "version": "0.2.2",
+  "description": "A polished Nuxt documentation layer powered by Ginko Content.",
+  "keywords": [
+    "content",
+    "documentation",
+    "i18n",
+    "markdown",
+    "nuxt"
+  ],
+  "homepage": "https://github.com/Mat4m0/lupinum-docs-shadcn#readme",
+  "bugs": {
+    "url": "https://github.com/Mat4m0/lupinum-docs-shadcn/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mat4m0/lupinum-docs-shadcn.git",
+    "directory": "layer"
+  },
+  "files": [
+    "app",
+    "i18n",
+    "modules",
+    "runtime",
+    "server",
+    "shared",
+    "content.js",
+    "content.ts",
+    "components.ts",
+    "icon-bundle.ts",
+    "index.d.ts",
+    "nuxt.config.ts",
+    "tags.ts",
+    "!**/*.test.ts"
+  ],
+  "type": "module",
+  "main": "./nuxt.config.ts",
+  "exports": {
+    ".": "./nuxt.config.ts",
+    "./content": {
+      "types": "./content.ts",
+      "import": "./content.js",
+      "default": "./content.js"
+    },
+    "./app-config": "./shared/types/app-config.ts",
+    "./components": "./components.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@iconify-json/circle-flags": "^1.2.10",
+    "@iconify-json/logos": "^1.2.11",
+    "@iconify-json/lucide": "^1.2.111",
+    "@nuxt/fonts": "^0.14.0",
+    "@nuxt/icon": "^2.2.3",
+    "@nuxt/image": "^2.0.0",
+    "@nuxt/kit": "^4.4.6",
+    "@nuxt/scripts": "^0.13.2",
+    "@nuxtjs/color-mode": "^4.0.0",
+    "@nuxtjs/i18n": "^10.4.0",
+    "@nuxtjs/mcp-toolkit": "0.17.2",
+    "@nuxtjs/robots": "^6.1.2",
+    "@nuxtjs/sitemap": "^8.2.2",
+    "@resvg/resvg-js": "^2.6.0",
+    "@shikijs/transformers": "^4.2.0",
+    "@tailwindcss/vite": "^4.3.0",
+    "@vueuse/core": "^14.2.1",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "h3": "^1.15.4",
+    "nitropack": "^2.13.4",
+    "nuxt-og-image": "^6.7.2",
+    "reka-ui": "^2.9.2",
+    "satori": "^0.19.2",
+    "shiki": "^4.0.2",
+    "tailwind-merge": "^3.5.0",
+    "tailwindcss": "^4.2.2",
+    "tw-animate-css": "^1.4.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@lupinum/ginko-content": ">=0.3.0-rc.2 <0.4.0",
+    "nuxt": "^4.4.6",
+    "vue": "^3.5.35",
+    "vue-router": "^5.1.0"
+  },
+  "scripts": {}
+}

package/runtime/markdown/inline-code-highlight.ts

@@ -0,0 +1,155 @@
+import type { ComarkElement, ComarkNode, ComarkPluginFactory } from "comark";
+import { getHighlighter, type HighlightOptions } from "comark/plugins/highlight";
+import { codeToTokens, getTokenStyleObject, stringifyTokenStyle } from "shiki/core";
+
+type CodeAttributes = {
+  class?: string;
+  lang?: string;
+  language?: string;
+};
+
+type ThemeRegistration = NonNullable<NonNullable<HighlightOptions["themes"]>["light"]>;
+
+type CodeThemes = {
+  light: ThemeRegistration;
+  dark: ThemeRegistration;
+};
+
+function cloneTheme<T extends ThemeRegistration>(theme: T): T {
+  return structuredClone(theme);
+}
+
+async function resolveCodeThemes(themes?: HighlightOptions["themes"]): Promise<CodeThemes> {
+  if (themes?.light || themes?.dark) {
+    const light = themes.light || themes.dark;
+    const dark = themes.dark || themes.light;
+
+    return {
+      light: cloneTheme(light as ThemeRegistration),
+      dark: cloneTheme(dark as ThemeRegistration),
+    };
+  }
+
+  const [light, dark] = await Promise.all([
+    import("shiki/dist/themes/material-theme-lighter.mjs"),
+    import("shiki/dist/themes/material-theme-palenight.mjs"),
+  ]);
+
+  return {
+    light: cloneTheme(light.default),
+    dark: cloneTheme(dark.default),
+  };
+}
+
+function getThemeName(theme: ThemeRegistration, fallback: string): string {
+  return typeof theme === "object" &&
+    theme !== null &&
+    "name" in theme &&
+    typeof theme.name === "string"
+    ? theme.name
+    : fallback;
+}
+
+function isElement(node: ComarkNode): node is ComarkElement {
+  return Array.isArray(node) && typeof node[0] === "string";
+}
+
+function getCodeLanguage(attrs: CodeAttributes): string | undefined {
+  const language = attrs.language ?? attrs.lang;
+
+  return language?.trim() || undefined;
+}
+
+function appendClass(attrs: CodeAttributes, className: string): CodeAttributes {
+  return {
+    ...attrs,
+    class: [attrs.class, className].filter(Boolean).join(" "),
+  };
+}
+
+async function highlightInlineCodeNode(
+  node: ComarkElement,
+  options: HighlightOptions,
+): Promise<ComarkElement> {
+  const attrs = (node[1] ?? {}) as CodeAttributes;
+  const language = getCodeLanguage(attrs);
+  const code = node
+    .slice(2)
+    .filter((child): child is string => typeof child === "string")
+    .join("");
+
+  if (!language || !code) {
+    return node;
+  }
+
+  const themes = await resolveCodeThemes(options.themes);
+  const lightThemeName = getThemeName(themes.light, "material-theme-lighter");
+  const darkThemeName = getThemeName(themes.dark, "material-theme-palenight");
+  const highlighter = await getHighlighter({
+    ...options,
+    registerDefaultThemes: false,
+    themes,
+  });
+  const result = codeToTokens(highlighter, code, {
+    lang: language,
+    themes: {
+      light: lightThemeName,
+      dark: lightThemeName !== darkThemeName ? darkThemeName : undefined,
+    },
+  });
+  const children: ComarkNode[] = [];
+
+  for (let lineIndex = 0; lineIndex < result.tokens.length; lineIndex += 1) {
+    const line = result.tokens[lineIndex] ?? [];
+
+    for (const token of line) {
+      const style = stringifyTokenStyle(token.htmlStyle || getTokenStyleObject(token));
+      children.push(style ? ["span", { style }, token.content] : ["span", {}, token.content]);
+    }
+
+    if (lineIndex < result.tokens.length - 1) {
+      children.push("\n");
+    }
+  }
+
+  return [
+    "code",
+    appendClass(attrs, `shiki ${result.themeName || ""} language-${language}`.trim()),
+    ...children,
+  ];
+}
+
+async function highlightInlineCodeChildren(
+  parent: ComarkElement,
+  options: HighlightOptions,
+): Promise<void> {
+  const insidePre = parent[0] === "pre";
+
+  for (let index = 2; index < parent.length; index += 1) {
+    const child = parent[index] as ComarkNode;
+
+    if (!isElement(child)) {
+      continue;
+    }
+
+    if (!insidePre && child[0] === "code") {
+      parent[index] = await highlightInlineCodeNode(child, options);
+      continue;
+    }
+
+    await highlightInlineCodeChildren(child, options);
+  }
+}
+
+const inlineCodeHighlightPlugin: ComarkPluginFactory<HighlightOptions> = (options = {}) => ({
+  name: "inline-code-highlight",
+  async post(state) {
+    for (const node of state.tree.nodes) {
+      if (isElement(node)) {
+        await highlightInlineCodeChildren(node, options);
+      }
+    }
+  },
+});
+
+export default inlineCodeHighlightPlugin;

package/runtime/server/agent-markdown.ts

@@ -0,0 +1,21 @@
+import {
+  registerAgentMarkdownSerializers,
+  type AgentMarkdownSerializer,
+  type AgentMarkdownSerializerMap,
+} from "@lupinum/ginko-content/agent-registry";
+import { contentComponentTags } from "../../tags";
+
+const renderXmlComponent: AgentMarkdownSerializer = (node, ctx) =>
+  ctx.xmlComponent(node.tag || "component", ctx.cleanProps(node), ctx.renderChildren(node));
+
+export const contentComponentAgentMarkdownTags = Object.keys(contentComponentTags);
+
+export function registerContentComponentAgentMarkdownSerializers() {
+  const serializers: AgentMarkdownSerializerMap = {};
+  for (const [tag, component] of Object.entries(contentComponentTags)) {
+    serializers[tag] = renderXmlComponent;
+    serializers[component] = renderXmlComponent;
+  }
+
+  registerAgentMarkdownSerializers(serializers);
+}

package/runtime/utils.ts

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

package/server/mcp/tools/get-page.ts

@@ -0,0 +1,14 @@
+import { defineMcpTool } from "@nuxtjs/mcp-toolkit/server";
+import { agentRawPathForRoute } from "@lupinum/ginko-content/agent-paths";
+import { z } from "zod";
+
+export default defineMcpTool({
+  description: "Read a documentation page as Markdown.",
+  annotations: { readOnlyHint: true },
+  inputSchema: {
+    path: z.string().startsWith("/").describe("Documentation path, for example /docs/introduction"),
+  },
+  handler: async ({ path }) => {
+    return await $fetch<string>(agentRawPathForRoute(path), { responseType: "text" });
+  },
+});

package/server/mcp/tools/list-pages.ts

@@ -0,0 +1,10 @@
+import { defineMcpTool } from "@nuxtjs/mcp-toolkit/server";
+
+export default defineMcpTool({
+  description: "List the documentation pages available to agents.",
+  annotations: { readOnlyHint: true },
+  handler: async () => {
+    const index = await $fetch<string>("/llms.txt", { responseType: "text" });
+    return index;
+  },
+});

package/server/plugins/agent-markdown.ts

@@ -0,0 +1,6 @@
+import { defineNitroPlugin } from "nitropack/runtime/plugin";
+import { registerContentComponentAgentMarkdownSerializers } from "../../runtime/server/agent-markdown";
+
+export default defineNitroPlugin(() => {
+  registerContentComponentAgentMarkdownSerializers();
+});

package/shared/route-slugs.ts

@@ -0,0 +1,5 @@
+export const routeSlugs = {
+  home: { en: "/", de: "/" },
+  docs: { en: "/docs", de: "/dokumentation" },
+  blog: { en: "/blog", de: "/blog" },
+} as const;

package/shared/types/app-config.ts

@@ -0,0 +1,100 @@
+export type GinkoDocsLocalizedText = { en: string; de?: string };
+
+export interface GinkoDocsLink {
+  label: GinkoDocsLocalizedText;
+  to: GinkoDocsLocalizedText;
+}
+
+export type GinkoDocsHeroMedia =
+  | { type: "image"; src: string; alt: string }
+  | { type: "code"; code: string; language?: string; filename?: string };
+
+export type GinkoDocsPlausibleExtension =
+  | "hash"
+  | "outbound-links"
+  | "file-downloads"
+  | "tagged-events"
+  | "revenue"
+  | "pageview-props"
+  | "compat"
+  | "local"
+  | "manual";
+
+export interface GinkoDocsAppConfig {
+  site: {
+    name: GinkoDocsLocalizedText;
+    description: GinkoDocsLocalizedText;
+    url: string;
+    logo: { light: string; dark: string };
+    localeSwitcher: "dropdown" | "segmented";
+    docsSidebarSwitcher: "dropdown" | "list" | "tabs";
+    lupinumAttribution: boolean;
+  };
+  nav: {
+    /** "auto" derives Docs (+ Blog when blog routes exist); an array overrides entirely. */
+    links: "auto" | GinkoDocsLink[];
+  };
+  banner: {
+    /** "auto" shows the banner when blog routes exist (legacy behavior). */
+    enabled: boolean | "auto";
+    /** Dismissal storage key — change it to re-show the banner after an update. */
+    id: string;
+    text?: GinkoDocsLocalizedText;
+    link?: { label?: GinkoDocsLocalizedText; to?: GinkoDocsLocalizedText };
+    showOnLanding: boolean;
+  };
+  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[];
+    };
+  };
+  social: {
+    github?: string;
+    linkedin?: string;
+  };
+  feedback: {
+    enabled: boolean;
+  };
+  ogImage: {
+    enabled: boolean;
+    /** OgImage template component name (file in app/components/OgImage/). */
+    component: string;
+  };
+  markdownActions: {
+    chatGpt: boolean;
+    claude: boolean;
+    mcp: boolean;
+  };
+  images: {
+    /** Click-to-zoom lightbox for prose images. */
+    zoom: boolean;
+  };
+  toc: {
+    depth: 2 | 3 | 4;
+  };
+  repository?: {
+    url: string;
+    branch?: string;
+    contentDirectory?: string;
+  };
+  landing: {
+    eyebrow?: GinkoDocsLocalizedText;
+    title: GinkoDocsLocalizedText;
+    description: GinkoDocsLocalizedText;
+    primary: GinkoDocsLink;
+    secondary?: GinkoDocsLink;
+    hero?: {
+      media?: GinkoDocsHeroMedia;
+    };
+    features: Array<{
+      title: GinkoDocsLocalizedText;
+      description: GinkoDocsLocalizedText;
+      icon?: string;
+    }>;
+  };
+}