@lupinum/ginko-docs 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthias Amon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# Ginko Docs
+
+Ginko Docs is a publishable Nuxt layer for focused, searchable, multilingual documentation sites. It combines a polished application shell with Ginko Content collections, navigation, search, SEO, localized routes, and agent-readable Markdown surfaces.
+
+The package currently lives in the Ginko Docs development repository. Repository links may move to the Lupinum organization without changing the package name or consumer API.
+
+## Install
+
+```sh
+pnpm add -D @lupinum/ginko-docs
+```
+
+Extend the layer from `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  extends: ["@lupinum/ginko-docs"],
+});
+```
+
+Define the site’s content collections in `content.config.ts`:
+
+```ts
+import { defineGinkoDocsConfig } from "@lupinum/ginko-docs/content";
+
+export default defineGinkoDocsConfig({
+  site: {
+    name: "Example Docs",
+    description: "Documentation for Example.",
+    url: "https://docs.example.com",
+  },
+  locales: ["en"],
+  defaultLocale: "en",
+  blog: false,
+});
+```
+
+The content configuration is the source of truth for whether the optional blog exists. The layer removes blog routes when no blog collection is configured and derives navigation visibility from the resulting router.
+
+Add public presentation settings in `app/app.config.ts`:
+
+```ts
+export default {
+  ginkoDocs: {
+    site: {
+      name: { en: "Example Docs" },
+      description: { en: "Documentation for Example." },
+      url: "https://docs.example.com",
+      logo: { light: "/logo.svg", dark: "/logo-dark.svg" },
+    },
+  },
+};
+```
+
+## Public exports
+
+- `@lupinum/ginko-docs` — Nuxt layer entry
+- `@lupinum/ginko-docs/content` — typed content configuration factory
+- `@lupinum/ginko-docs/app-config` — application-configuration types
+- `@lupinum/ginko-docs/components` — default MDC tag map and related types
+
+## Customize
+
+Consumers use Nuxt's ordinary override rules. Add `app/pages/index.vue` or a layout to replace a
+page or layout. Add a same-named `SiteHeader`, `SiteFooter`, `SiteBanner`, `SiteLogoMark`,
+`SiteLocaleSwitcher`, `SiteInteractionLayer`, or `DocsSidebar` component to replace that shell
+piece. Import consumer theme CSS from an app plugin so it augments rather than replaces the layer's
+styles. Add or replace MDC components in `app/components/mdc` and extend
+`ginkoDocsComponentTags` from `@lupinum/ginko-docs/components` in `content.markdown.tags`. Register
+custom MDC components globally with a Nuxt plugin or Nuxt's `.global.vue` filename suffix, because
+MDC resolves tag targets dynamically. Each new tag must also declare its narrow static prop and slot
+contract in `content.componentPolicy`; Nuxt merges that consumer entry with the layer's built-in
+policy.
+
+Custom agent Markdown is deliberately separate: register serializers through
+`@lupinum/ginko-content/agent-registry` in a Nitro plugin.
+
+## Configuration
+
+All features are configured under the `ginkoDocs` key in `app/app.config.ts` and ship with safe
+defaults:
+
+- `nav.links` — `"auto"` (Docs + Blog when present) or an array of localized links.
+- `banner` — announcement bar with persisted dismissal (`enabled: "auto" | boolean`, `id`, `text`,
+  `link`, `showOnLanding`).
+- `analytics.plausible` — Plausible via Nuxt Scripts; disabled until `domain` is set
+  (`scriptSrc` for self-hosted, `extensions` default `["outbound-links"]`).
+- `feedback.enabled` — "Was this page helpful?" widget; votes fire the `docs-feedback` Plausible
+  event and negative votes link to a prefilled GitHub issue when `repository` is configured.
+- `ogImage` — build-time PNG social cards (`enabled`, `component`); override the template by
+  shadowing `app/components/OgImage/GinkoDocs.satori.vue`.
+- `markdownActions` — toggle ChatGPT / Claude / MCP entries in the Copy Markdown menu.
+- `images.zoom` — click-to-zoom lightbox for prose images.
+- `toc.depth` — table-of-contents depth (2–4).
+- `landing.hero.media` — optional hero visual (`{ type: "code" }` or `{ type: "image" }`).
+- `repository` — enables "Edit this page" / "Report an issue" links.
+
+The bare docs root (e.g. `/docs`) redirects to the first documentation page, and the 404 page
+renders with the full site chrome.
+
+## Agent surfaces
+
+The layer can expose canonical content through raw Markdown negotiation, `/raw/**`, `/llms.txt`, `/llms-full.txt`, and read-only MCP tools. These surfaces use the same Ginko Content route and document model as rendered pages.
+
+## Requirements
+
+- Nuxt 4.4 or newer
+- A package manager supported by Nuxt
+
+## License
+
+[MIT](./LICENSE)

package/app/app.config.ts

@@ -0,0 +1,49 @@
+import type { GinkoDocsAppConfig } from "../shared/types/app-config";
+export default {
+  ginkoDocs: {
+    site: {
+      name: { en: "Ginko Docs", de: "Ginko Docs" },
+      description: {
+        en: "Beautiful documentation sites built with Nuxt and ginko-content.",
+        de: "Schöne Dokumentations-Websites auf Basis von Nuxt und ginko-content.",
+      },
+      url: "http://localhost:3000",
+      logo: { light: "/logo.svg", dark: "/logo-dark.svg" },
+      localeSwitcher: "dropdown",
+      docsSidebarSwitcher: "tabs",
+      lupinumAttribution: true,
+    },
+    nav: { links: "auto" },
+    banner: {
+      enabled: "auto",
+      id: "default",
+      showOnLanding: true,
+    },
+    social: {},
+    feedback: { enabled: false },
+    ogImage: { enabled: true, component: "GinkoDocs" },
+    markdownActions: { chatGpt: true, claude: true, mcp: true },
+    images: { zoom: true },
+    toc: { depth: 3 },
+    repository: undefined,
+    landing: {
+      eyebrow: {
+        en: "Documentation for humans and agents",
+        de: "Dokumentation für Menschen und Agenten",
+      },
+      title: {
+        en: "Documentation that feels finished.",
+        de: "Dokumentation, die sich fertig anfühlt.",
+      },
+      description: {
+        en: "A focused Nuxt layer for fast, searchable, multilingual documentation sites.",
+        de: "Ein fokussierter Nuxt-Layer für schnelle, durchsuchbare, mehrsprachige Dokumentations-Websites.",
+      },
+      primary: {
+        label: { en: "Get started", de: "Erste Schritte" },
+        to: { en: "/docs", de: "/de/dokumentation" },
+      },
+      features: [],
+    },
+  } satisfies GinkoDocsAppConfig,
+};

package/app/app.vue

@@ -0,0 +1,71 @@
+<script setup lang="ts">
+import { getLocalizedSiteText } from "#ginko-docs/config/site.utils";
+import { useAppConfig, useHead, useI18n, useRoute, useSeoMeta } from "#imports";
+import { useLocalizedRouteSwitch } from "#ginko-docs/composables/useLocalizedRouteSwitch";
+import { useCanonicalUrl } from "#ginko-docs/composables/useCanonicalUrl";
+import { useGinkoAnalytics } from "#ginko-docs/composables/useGinkoAnalytics";
+import { useGinkoOgImage } from "#ginko-docs/composables/useGinkoOgImage";
+import { useSchemaJsonLd } from "#ginko-docs/composables/useSchemaJsonLd";
+import { defaultLocale } from "../i18n/locales";
+
+const canonicalUrl = useCanonicalUrl();
+const { locale, locales } = useI18n();
+const route = useRoute();
+const { switchPathname } = useLocalizedRouteSwitch();
+const docsConfig = useAppConfig().ginkoDocs;
+const siteUrl = docsConfig.site.url;
+
+useSeoMeta({
+  ogUrl: canonicalUrl,
+  twitterCard: "summary_large_image",
+});
+
+// Site-wide baseline: every route gets a generated PNG social card, with the
+// title/description auto-derived from the page's own useSeoMeta values.
+useGinkoOgImage({ locale: locale.value });
+useGinkoAnalytics();
+
+useSchemaJsonLd(() => [
+  {
+    "@type": "WebSite",
+    name: getLocalizedSiteText(docsConfig.site.name, locale.value),
+    description: getLocalizedSiteText(docsConfig.site.description, locale.value),
+    url: siteUrl,
+    inLanguage: locale.value,
+  },
+]);
+
+useHead(() => ({
+  htmlAttrs: {
+    lang: locale.value,
+  },
+  link: [
+    { key: "canonical", rel: "canonical", href: canonicalUrl.value },
+    ...locales.value.map((entry) => {
+      const code = typeof entry === "string" ? entry : entry.code;
+      const language = typeof entry === "string" ? entry : (entry.language ?? entry.code);
+      return {
+        key: `alternate-${code}`,
+        rel: "alternate",
+        hreflang: language,
+        href: new URL(switchPathname(code) || route.path, siteUrl).toString(),
+      };
+    }),
+    {
+      key: "alternate-x-default",
+      rel: "alternate",
+      hreflang: "x-default",
+      href: new URL(switchPathname(defaultLocale) || route.path, siteUrl).toString(),
+    },
+  ],
+}));
+</script>
+
+<template>
+  <div role="region" aria-label="Route announcements" aria-live="polite" class="sr-only">
+    <NuxtRouteAnnouncer />
+  </div>
+  <NuxtLayout>
+    <NuxtPage />
+  </NuxtLayout>
+</template>