@lupinum/ginko-docs 0.3.0-rc.4 → 0.3.0

package/README.md

@@ -1,169 +1,78 @@
-# Ginko Docs
+<p align="center">
+  <img src="https://raw.githubusercontent.com/lupinum-dev/ginko-docs/main/docs/public/web-app-manifest-512x512.png" width="128" alt="Ginko Docs icon">
+</p>
 
-Ginko Docs is a Nuxt layer for focused documentation sites. It combines Ginko Content collections with a documentation shell, navigation, search, localization, SEO, social images, optional blog routes, and agent-readable Markdown surfaces.
+<h1 align="center">@lupinum/ginko-docs</h1>
 
-## Requirements
+<p align="center">Add a complete documentation experience to a Nuxt application through one reusable layer.</p>
 
-- Node.js `^22.18.0 || ^24.11.0 || >=26.0.0`
-- Nuxt `>=4.4.7 <5`
-- Vue `^3.5.35`
-- Vue Router `^5.1.0`
-- Ginko Content `>=0.4.0-rc.1 <0.5.0`
+<p align="center">
+  <a href="https://www.npmjs.com/package/@lupinum/ginko-docs"><img src="https://img.shields.io/npm/v/@lupinum/ginko-docs?color=00DC82" alt="npm version"></a>
+  <a href="https://github.com/lupinum-dev/ginko-docs/actions/workflows/ci.yml"><img src="https://github.com/lupinum-dev/ginko-docs/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
+  <a href="https://github.com/lupinum-dev/ginko-docs/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
+</p>
 
-## Install
+> [!WARNING]
+> This package is stable in the 0.3 release line. Because it is pre-1.0, a later minor release can contain breaking changes.
 
-Install the layer and its Ginko Content peer:
+## Purpose
 
-```bash
-pnpm add -D @lupinum/ginko-docs@0.3.0-rc.4 @lupinum/ginko-content@0.4.0-rc.1
-```
+Use this package when a Nuxt application needs documentation routes, navigation, search, localization, metadata, social images, feedback, and agent-readable content. The layer provides the interface while the consuming application keeps ownership of its content and identity.
 
-Keep the public identity in one shared value:
+## Requirements
 
-```json [site.json]
-{
-  "name": "Example Docs",
-  "description": "Documentation for Example.",
-  "url": "https://docs.example.com"
-}
-```
+- Node.js 22.18, 24.11, or 26 and later maintenance releases
+- Nuxt 4.5.1 or later in the Nuxt 4 line
+- Vue 3.5.35 or later
+- Ginko Content 0.4 prerelease or later in the 0.4 line
 
-Extend the layer and configure the canonical origin:
+## Installation
 
-```ts [nuxt.config.ts]
-import site from "./site.json" with { type: "json" };
+```bash
+pnpm add -D @lupinum/ginko-docs@0.3.0 @lupinum/ginko-content@0.4.0-rc.2
+```
 
+```ts
 export default defineNuxtConfig({
   extends: ["@lupinum/ginko-docs"],
-  site: { url: site.url },
-  i18n: { baseUrl: site.url },
+  site: { url: "https://docs.example.com" },
+  i18n: { baseUrl: "https://docs.example.com" },
 });
 ```
 
-Define the content collections in `content.config.ts`:
+## Quick start
 
-```ts [content.config.ts]
+```ts
 import { defineGinkoDocsConfig } from "@lupinum/ginko-docs/content";
-import site from "./site.json" with { type: "json" };
 
 export default defineGinkoDocsConfig({
-  site,
+  site: {
+    name: "Example Docs",
+    description: "Documentation for Example.",
+    url: "https://docs.example.com",
+  },
   locales: ["en"],
   blog: false,
 });
 ```
 
-Single-locale documentation belongs in `content/docs`. Add a first page:
-
-```md [content/docs/1.introduction.md]
----
-title: Introduction
-description: Learn what Example does and how to use it.
----
-
-Example solves ...
-```
-
-The bare `/docs` route redirects to the first navigable document.
-
-## Set the public identity
-
-Presentation settings live in `app/app.config.ts`:
-
-```ts [app/app.config.ts]
-import site from "../site.json";
-
-export default defineAppConfig({
-  ginkoDocs: {
-    site: {
-      name: { en: site.name },
-      description: { en: site.description },
-      url: site.url,
-      logo: { light: "/logo.svg", dark: "/logo-dark.svg" },
-      docsSidebarSwitcher: "tabs",
-      lupinumAttribution: true,
-    },
-    nav: { links: "auto" },
-    banner: { enabled: false, id: "default", showOnLanding: true },
-    feedback: { enabled: false },
-    toc: { depth: 3 },
-  },
-});
-```
-
-Localized values use `{ en, de? }`. Use English as the default locale; supported content layouts are English-only and bilingual English/German.
-
-Set the production URL once in `site.json`, then pass it to the content configuration, app configuration, Nuxt Site configuration, and Nuxt i18n `baseUrl`. JSON keeps the shared identity portable across each configuration loader. The layer uses it for canonical links, structured data, social cards, and agent catalogs.
-
-## Enable the blog
-
-Set `blog: true` in `defineGinkoDocsConfig`. That single option creates the `blog` and `authors` collections and keeps the blog routes in the generated Nuxt application.
-
-Blog posts are flat Markdown files under `content/2.blog` for an English-only site, or the corresponding locale directory for a bilingual site. Each post requires `title`, `description`, `date`, `readingTime`, and an `author` reference. Author records live under `authors` and require `slug`, `name`, `role`, `bio`, and `avatar`.
-
-## Customize presentation
-
-Use Nuxt's normal application directories. A consumer can replace `app/pages/index.vue`, layouts, or a stable shell component by providing the same component name:
-
-- `SiteHeader`, `SiteFooter`, `SiteBanner`, `SiteLogoMark`
-- `SiteLocaleSwitcher`, `SiteInteractionLayer`, `DocsSidebar`
-
-Load consumer theme CSS from an app plugin so it follows the layer styles without replacing Nuxt's merged `css` array.
-
-To add an authored MDC component, extend the exported tag map and declare its static render policy:
-
-```ts [nuxt.config.ts]
-import { ginkoDocsComponentTags } from "@lupinum/ginko-docs/components";
-
-export default defineNuxtConfig({
-  content: {
-    componentPolicy: {
-      components: {
-        "api-playground": {
-          kind: "block",
-          props: {
-            method: { type: "string", required: true },
-            path: { type: "string", required: true },
-          },
-          slots: ["default"],
-          media: null,
-        },
-      },
-    },
-    markdown: {
-      tags: {
-        ...ginkoDocsComponentTags,
-        "api-playground": "MdcApiPlayground",
-      },
-    },
-  },
-});
-```
-
-Register the Vue component globally because Markdown resolves component targets dynamically. Register a serializer through `@lupinum/ginko-content/agent-registry` when copied and raw Markdown needs a representation other than the default XML-style component output.
-
-## Agent and discovery surfaces
+Put Markdown files in `content/docs`. Open `/docs` after the Nuxt server starts.
 
-Every deployment can include the prerendered routes and assets:
+## Exports
 
-- `/raw/**.md`
-- `/llms.txt` and `/llms-full.txt`
-- localized LLM catalogs
-- sitemap, robots, and PNG social images
+- `@lupinum/ginko-docs` is the Nuxt layer entry.
+- `@lupinum/ginko-docs/content` exports `defineGinkoDocsConfig`.
+- `@lupinum/ginko-docs/app-config` exports application configuration types.
+- `@lupinum/ginko-docs/components` exports the public MDC component contract.
 
-A Nitro server also provides request-time `Accept: text/markdown` negotiation, response link headers, and `/mcp`. The MCP server exposes read-only `list-pages` and `get-page` tools. Plain static hosting cannot provide those request-time behaviors.
+## Documentation
 
-The `markdownActions` app settings change the page menu only; they do not disable agent routes.
+Read the [Ginko Docs documentation](https://ginko-docs.lupinum.com) and the [root README](https://github.com/lupinum-dev/ginko-docs#readme).
 
-## Public exports
+## Support and security
 
-| Export                           | Contents                                                      |
-| -------------------------------- | ------------------------------------------------------------- |
-| `@lupinum/ginko-docs`            | Nuxt layer entry                                              |
-| `@lupinum/ginko-docs/content`    | `defineGinkoDocsConfig`                                       |
-| `@lupinum/ginko-docs/app-config` | App-configuration types                                       |
-| `@lupinum/ginko-docs/components` | Tag map, component names, component policy, and related types |
+Use [GitHub issues](https://github.com/lupinum-dev/ginko-docs/issues) or the [Lupinum OSS Discord](https://discord.gg/RPH6SeA36N) for support. Report vulnerabilities through the [private security process](https://github.com/lupinum-dev/ginko-docs/security/policy).
 
 ## License
 
-[MIT](./LICENSE)
+Released by [Lupinum OG](https://lupinum.com) under the [MIT License](https://github.com/lupinum-dev/ginko-docs/blob/main/LICENSE).

package/app/app.config.ts

@@ -4,6 +4,7 @@ export default {
     theme: {
       neutral: "zinc",
       primary: "neutral",
+      codeBlocks: "dark",
     },
     prose: {
       appearance: "tint",

package/app/assets/css/prose.css

@@ -5,7 +5,7 @@
   --content-prose-heading-foreground: color-mix(in oklab, var(--foreground) 90%, transparent);
   /* Inline code belongs to its surrounding surface; monospace type carries
      the distinction without adding a nested chip background. */
-  --content-prose-inline-code-background: transparent;
+  --content-prose-inline-code-background: var(--background);
   --content-prose-inline-code-foreground: var(--foreground);
   --content-prose-code-highlight-border: var(--code-border);
   /* Kept light enough that Shiki's light-plus tokens stay WCAG AA on top. */
@@ -303,6 +303,7 @@
   border-radius: max(0.3125rem, calc(var(--radius) - 5px));
   box-decoration-break: clone;
   -webkit-box-decoration-break: clone;
+  border: 1px solid color-mix(in oklab, var(--foreground) 15%, transparent);
   background-color: var(--content-prose-inline-code-background, var(--muted));
   color: var(--content-prose-inline-code-foreground, var(--foreground));
   /* em-based so chips scale with tables, callouts, and body text alike */
@@ -420,6 +421,37 @@ html.dark .shiki span {
   text-decoration: var(--shiki-dark-text-decoration, inherit) !important;
 }
 
+/* Code blocks default to a stable dark presentation in either page theme.
+   "adaptive" leaves these local tokens unset and follows the page tokens. */
+html[data-code-blocks="dark"] :where(.content-codeblock, .content-codegroup, .content-code-tree) {
+  --background: var(--theme-neutral-950);
+  --foreground: var(--theme-neutral-50);
+  --card: var(--theme-neutral-900);
+  --card-foreground: var(--theme-neutral-50);
+  --primary: var(--theme-primary-dark);
+  --primary-foreground: var(--theme-primary-dark-foreground);
+  --secondary: var(--theme-neutral-800);
+  --secondary-foreground: var(--theme-neutral-50);
+  --muted: var(--theme-neutral-800);
+  --muted-foreground: var(--theme-neutral-400);
+  --accent: var(--theme-neutral-800);
+  --accent-foreground: var(--theme-neutral-50);
+  --code: var(--theme-neutral-900);
+  --code-foreground: var(--theme-neutral-50);
+  --code-border: var(--theme-neutral-800);
+  --border: var(--theme-neutral-800);
+  --input: var(--theme-neutral-700);
+  --ring: var(--theme-primary-dark-ring);
+}
+
+html[data-code-blocks="dark"] .content-codeblock.shiki span {
+  background-color: var(--shiki-dark-bg, transparent);
+  color: var(--shiki-dark) !important;
+  font-style: var(--shiki-dark-font-style, inherit) !important;
+  font-weight: var(--shiki-dark-font-weight, inherit) !important;
+  text-decoration: var(--shiki-dark-text-decoration, inherit) !important;
+}
+
 [data-fd-codeblock] {
   background-color: var(--secondary);
   color: var(--foreground);

package/app/components/site/ModeToggle.vue

@@ -1,20 +1,18 @@
 <script setup lang="ts">
 import type { HTMLAttributes } from "vue";
-import { Button } from "#ginko-docs/components/ui/button";
 import { computed } from "vue";
 import { useColorMode, useI18n } from "#imports";
 import { cn } from "#ginko-docs/utils";
+import { headerUtilityButtonClass } from "#ginko-docs/components/site/header-utils";
 import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuRadioGroup,
-  DropdownMenuRadioItem,
-  DropdownMenuTrigger,
-} from "#ginko-docs/components/ui/dropdown-menu";
+  nextColorModePreference,
+  themeToggleIcon,
+  themeToggleLabelKey,
+} from "#ginko-docs/components/site/mode-toggle.utils";
 
 const props = withDefaults(
   defineProps<{
-    variant?: "icon" | "menu-row" | "menu-tile" | "pill";
+    variant?: "icon" | "menu-row";
     class?: HTMLAttributes["class"];
   }>(),
   {
@@ -25,108 +23,59 @@ const props = withDefaults(
 const colorMode = useColorMode();
 const { t } = useI18n();
 
-const colorModeOptions = [
-  { value: "light", labelKey: "theme.light", icon: "lucide:sun" },
-  { value: "dark", labelKey: "theme.dark", icon: "lucide:moon" },
-  { value: "system", labelKey: "theme.system", icon: "lucide:monitor" },
-] as const;
+const isDark = computed(() => colorMode.value === "dark");
+const toggleIcon = computed(() => themeToggleIcon(isDark.value));
+const toggleLabel = computed(() => t(themeToggleLabelKey(isDark.value)));
 
-type ColorModePreference = (typeof colorModeOptions)[number]["value"];
-
-const selectedColorModeOption = computed(
-  () =>
-    colorModeOptions.find((option) => option.value === colorMode.preference) ??
-    colorModeOptions.find((option) => option.value === "system")!,
-);
-const triggerIcon = computed(() => selectedColorModeOption.value.icon);
-const nextExplicitColorModeIcon = computed(() =>
-  colorMode.value === "dark" ? "lucide:sun" : "lucide:moon",
-);
-const triggerLabel = computed(() => t(selectedColorModeOption.value.labelKey));
-
-function isColorModePreference(value: string): value is ColorModePreference {
-  return colorModeOptions.some((option) => option.value === value);
-}
-
-function setColorModePreference(value: unknown) {
-  if (typeof value === "string" && isColorModePreference(value)) {
-    colorMode.preference = value;
-  }
+function toggleColorMode() {
+  const currentRendered = isDark.value ? "dark" : "light";
+  colorMode.preference = nextColorModePreference(currentRendered);
 }
 </script>
 
 <template>
-  <DropdownMenu>
-    <DropdownMenuTrigger as-child>
-      <Button
-        v-if="variant === 'menu-row' || variant === 'menu-tile'"
-        variant="ghost"
-        :class="
-          cn(
-            variant === 'menu-tile'
-              ? 'h-14 w-full justify-between rounded-none px-3.5 text-sm font-semibold hover:bg-muted/40'
-              : 'h-[4.25rem] w-full justify-between rounded-none px-5 text-base font-semibold hover:bg-transparent',
-            props.class,
-          )
-        "
-      >
-        <span
-          class="flex min-w-0 items-center"
-          :class="variant === 'menu-tile' ? 'gap-3' : 'gap-4'"
-        >
-          <span
-            class="flex shrink-0 items-center justify-center rounded-lg bg-muted/60 text-foreground"
-            :class="variant === 'menu-tile' ? 'size-8' : 'size-11'"
-          >
-            <Icon
-              :name="triggerIcon"
-              :class="variant === 'menu-tile' ? 'size-4' : 'size-5'"
-              aria-hidden="true"
-            />
-          </span>
-          <span class="truncate">{{
-            variant === "menu-tile" ? triggerLabel : t("theme.label")
-          }}</span>
-        </span>
-        <Icon
-          :name="variant === 'menu-tile' ? 'lucide:chevron-down' : 'lucide:chevron-right'"
-          :class="variant === 'menu-tile' ? 'size-4' : 'size-5'"
-          class="text-muted-foreground"
-          aria-hidden="true"
-        />
-      </Button>
-      <Button
-        v-else-if="variant === 'pill'"
-        variant="outline"
-        :class="cn('h-9 gap-2 rounded-full px-4 text-sm font-semibold', props.class)"
-      >
-        <Icon :name="triggerIcon" class="size-4" aria-hidden="true" />
-        <span>{{ triggerLabel }}</span>
-        <span class="sr-only">{{ t("theme.toggle") }}</span>
-      </Button>
-      <Button v-else variant="outline" size="icon" :class="cn('relative shrink-0', props.class)">
-        <Icon :name="nextExplicitColorModeIcon" class="size-[1.2rem]" aria-hidden="true" />
-        <span class="sr-only">{{ t("theme.toggle") }}</span>
-      </Button>
-    </DropdownMenuTrigger>
-    <DropdownMenuContent align="end" class="w-44" :portal-disabled="variant !== 'icon'">
-      <DropdownMenuRadioGroup
-        :model-value="colorMode.preference"
-        @update:model-value="setColorModePreference"
+  <button
+    v-if="variant === 'menu-row'"
+    type="button"
+    role="switch"
+    :aria-checked="isDark"
+    :aria-label="toggleLabel"
+    :class="
+      cn(
+        'flex h-14 w-full items-center justify-between rounded-none px-5 text-base font-semibold hover:bg-transparent',
+        props.class,
+      )
+    "
+    @click="toggleColorMode"
+  >
+    <span class="flex min-w-0 items-center gap-4">
+      <span
+        class="flex size-11 shrink-0 items-center justify-center rounded-lg bg-muted/60 text-foreground"
       >
-        <DropdownMenuRadioItem
-          v-for="option in colorModeOptions"
-          :key="option.value"
-          :value="option.value"
-          class="gap-3"
-        >
-          <template #indicator-icon>
-            <Icon name="lucide:check" class="size-4" aria-hidden="true" />
-          </template>
-          <Icon :name="option.icon" class="size-4" aria-hidden="true" />
-          <span>{{ t(option.labelKey) }}</span>
-        </DropdownMenuRadioItem>
-      </DropdownMenuRadioGroup>
-    </DropdownMenuContent>
-  </DropdownMenu>
+        <Icon :name="toggleIcon" class="size-5" aria-hidden="true" />
+      </span>
+      <span class="truncate">{{ t("theme.label") }}</span>
+    </span>
+    <span
+      class="relative inline-flex h-6 w-11 shrink-0 rounded-full border border-border bg-muted/60 transition-colors"
+      :class="isDark ? 'bg-foreground/80' : ''"
+      aria-hidden="true"
+    >
+      <span
+        class="absolute top-0.5 size-5 rounded-full bg-background shadow-xs transition-transform motion-reduce:transition-none"
+        :class="isDark ? 'translate-x-[1.375rem]' : 'translate-x-0.5'"
+      />
+    </span>
+  </button>
+  <button
+    v-else
+    type="button"
+    role="switch"
+    :aria-checked="isDark"
+    :aria-label="toggleLabel"
+    :class="cn(headerUtilityButtonClass, props.class)"
+    @click="toggleColorMode"
+  >
+    <Icon :name="toggleIcon" class="size-[18px]" aria-hidden="true" />
+  </button>
 </template>