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

package/app/components/site/SiteLocaleSwitcher.vue

@@ -11,9 +11,10 @@ import { cn } from "#ginko-docs/utils";
 import { computed } from "vue";
 import { useI18n } from "#imports";
 import { useLocalizedRouteSwitch } from "#ginko-docs/composables/useLocalizedRouteSwitch";
+import { headerUtilityButtonClass } from "#ginko-docs/components/site/header-utils";
 import { locales as configuredLocales } from "../../../i18n/locales";
 
-type LocaleSwitcherVariant = "dropdown" | "menu-row" | "menu-tile" | "segmented" | "pill";
+type LocaleSwitcherVariant = "dropdown" | "menu-row";
 
 type LocaleEntry = {
   code: string;
@@ -21,7 +22,6 @@ type LocaleEntry = {
   name?: string;
   nativeName?: string;
   shortLabel?: string;
-  flagIcon?: string;
 };
 
 const props = withDefaults(
@@ -56,7 +56,6 @@ function normalizeLocale(entry: string | LocaleEntry) {
       name: configured?.name ?? entry.toUpperCase(),
       nativeName: configured?.nativeName ?? configured?.name ?? entry.toUpperCase(),
       shortLabel: configured?.shortLabel ?? entry.toUpperCase(),
-      flagIcon: configured?.flagIcon,
     };
   }
 
@@ -68,7 +67,6 @@ function normalizeLocale(entry: string | LocaleEntry) {
     nativeName:
       entry.nativeName ?? entry.name ?? configured?.nativeName ?? entry.code.toUpperCase(),
     shortLabel: entry.shortLabel ?? configured?.shortLabel ?? entry.code.toUpperCase(),
-    flagIcon: entry.flagIcon ?? configured?.flagIcon,
   };
 }
 
@@ -86,11 +84,6 @@ const localeLinks = computed(() =>
 const currentLocale = computed(
   () => localeLinks.value.find((entry) => entry.current) ?? localeLinks.value[0],
 );
-const currentMobileLocaleLabel = computed(() => {
-  const code = currentLocale.value?.code;
-  if (!code) return "";
-  return currentLocale.value?.name ?? code.toUpperCase();
-});
 
 function trackLocaleNavigation(_entry: { code: string; current: boolean; to: unknown }) {
   emit("navigate");
@@ -105,22 +98,11 @@ function trackLocaleNavigation(_entry: { code: string; current: boolean; to: unk
     <ClientOnly>
       <DropdownMenu>
         <DropdownMenuTrigger as-child>
-          <Button variant="ghost" class="h-9 gap-1.5 px-2.5" :aria-label="t('nav.language')">
-            <Icon
-              v-if="currentLocale?.flagIcon"
-              :name="currentLocale.flagIcon"
-              class="size-4 rounded-full"
-              aria-hidden="true"
-            />
-            <span class="text-xs font-semibold">{{ currentLocale?.shortLabel }}</span>
-            <Icon
-              name="lucide:chevron-down"
-              class="size-3.5 text-muted-foreground"
-              aria-hidden="true"
-            />
-          </Button>
+          <button type="button" :class="headerUtilityButtonClass" :aria-label="t('nav.language')">
+            <Icon name="lucide:languages" class="size-[18px]" aria-hidden="true" />
+          </button>
         </DropdownMenuTrigger>
-        <DropdownMenuContent align="end" class="w-44">
+        <DropdownMenuContent align="end" class="w-52">
           <DropdownMenuItem v-for="entry in localeLinks" :key="entry.code" as-child>
             <NuxtLink
               :to="entry.to"
@@ -128,17 +110,13 @@ function trackLocaleNavigation(_entry: { code: string; current: boolean; to: unk
               :lang="entry.code"
               :aria-label="entry.name"
               :aria-current="entry.current ? 'page' : undefined"
-              class="flex w-full items-center gap-2"
+              class="flex w-full items-center gap-3"
               @click="trackLocaleNavigation(entry)"
             >
-              <Icon
-                v-if="entry.flagIcon"
-                :name="entry.flagIcon"
-                class="size-4 rounded-full"
-                aria-hidden="true"
-              />
+              <span class="w-7 text-xs font-semibold tracking-wide text-muted-foreground">{{
+                entry.shortLabel
+              }}</span>
               <span class="flex-1">{{ entry.nativeName }}</span>
-              <span class="text-xs text-muted-foreground">{{ entry.shortLabel }}</span>
               <Icon
                 v-if="entry.current"
                 name="lucide:check"
@@ -151,76 +129,39 @@ function trackLocaleNavigation(_entry: { code: string; current: boolean; to: unk
       </DropdownMenu>
 
       <template #fallback>
-        <!-- Reserves the trigger's box before hydration. -->
-        <span class="inline-flex h-9 w-[4.25rem] rounded-md" aria-hidden="true" />
+        <span class="inline-flex size-9 shrink-0 rounded-lg" aria-hidden="true" />
       </template>
     </ClientOnly>
   </div>
 
   <div
-    v-else-if="
-      localeLinks.length > 1 &&
-      (variant === 'menu-row' || variant === 'menu-tile' || variant === 'pill')
-    "
+    v-else-if="localeLinks.length > 1 && variant === 'menu-row'"
     :class="cn('items-center', props.class)"
   >
     <DropdownMenu>
       <DropdownMenuTrigger as-child>
         <Button
-          v-if="variant === 'pill'"
-          variant="outline"
-          class="h-9 gap-2 rounded-full px-4 text-sm font-semibold"
-          :aria-label="t('nav.language')"
-        >
-          <Icon
-            v-if="currentLocale?.flagIcon"
-            :name="currentLocale.flagIcon"
-            class="size-4 rounded-full"
-            aria-hidden="true"
-          />
-          <span>{{ currentLocale?.shortLabel }}</span>
-        </Button>
-        <Button
-          v-else
           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',
-            )
-          "
+          class="h-14 w-full justify-between rounded-none px-5 text-base font-semibold hover:bg-transparent"
           :aria-label="t('nav.language')"
         >
-          <span
-            class="flex min-w-0 items-center"
-            :class="variant === 'menu-tile' ? 'gap-3' : 'gap-4'"
-          >
+          <span class="flex min-w-0 items-center gap-4">
             <span
-              v-if="variant === 'menu-tile' && currentLocale?.flagIcon"
-              class="flex size-8 shrink-0 items-center justify-center rounded-lg bg-muted/60"
+              class="flex size-11 shrink-0 items-center justify-center rounded-lg bg-muted/60 text-foreground"
             >
-              <Icon :name="currentLocale.flagIcon" class="size-5 rounded-full" aria-hidden="true" />
-            </span>
-            <Icon
-              v-else-if="currentLocale?.flagIcon"
-              :name="currentLocale.flagIcon"
-              class="size-7 shrink-0 rounded-full"
-              aria-hidden="true"
-            />
-            <span class="truncate">
-              {{ variant === "menu-tile" ? currentMobileLocaleLabel : currentLocale?.shortLabel }}
+              <Icon name="lucide:languages" class="size-5" aria-hidden="true" />
             </span>
+            <span class="truncate">{{ t("nav.languageLabel") }}</span>
+          </span>
+          <span class="flex items-center gap-2 text-muted-foreground">
+            <span class="text-sm font-semibold text-foreground">{{
+              currentLocale?.nativeName
+            }}</span>
+            <Icon name="lucide:chevron-down" class="size-5" aria-hidden="true" />
           </span>
-          <Icon
-            name="lucide:chevron-down"
-            class="text-muted-foreground"
-            :class="variant === 'menu-tile' ? 'size-4' : 'size-5'"
-            aria-hidden="true"
-          />
         </Button>
       </DropdownMenuTrigger>
-      <DropdownMenuContent align="end" class="w-44" portal-disabled>
+      <DropdownMenuContent align="end" class="w-52" portal-disabled>
         <DropdownMenuItem v-for="entry in localeLinks" :key="entry.code" as-child>
           <NuxtLink
             :to="entry.to"
@@ -228,17 +169,13 @@ function trackLocaleNavigation(_entry: { code: string; current: boolean; to: unk
             :lang="entry.code"
             :aria-label="entry.name"
             :aria-current="entry.current ? 'page' : undefined"
-            class="flex w-full items-center gap-2"
+            class="flex w-full items-center gap-3"
             @click="trackLocaleNavigation(entry)"
           >
-            <Icon
-              v-if="entry.flagIcon"
-              :name="entry.flagIcon"
-              class="size-4 rounded-full"
-              aria-hidden="true"
-            />
+            <span class="w-7 text-xs font-semibold tracking-wide text-muted-foreground">{{
+              entry.shortLabel
+            }}</span>
             <span class="flex-1">{{ entry.nativeName }}</span>
-            <span class="text-xs text-muted-foreground">{{ entry.shortLabel }}</span>
             <Icon
               v-if="entry.current"
               name="lucide:check"
@@ -250,35 +187,4 @@ function trackLocaleNavigation(_entry: { code: string; current: boolean; to: unk
       </DropdownMenuContent>
     </DropdownMenu>
   </div>
-
-  <div
-    v-else-if="localeLinks.length > 1"
-    :class="cn('items-center gap-1 rounded-md border border-border p-0.5', props.class)"
-    :aria-label="t('nav.language')"
-  >
-    <NuxtLink
-      v-for="entry in localeLinks"
-      :key="entry.code"
-      :to="entry.to"
-      :hreflang="entry.language"
-      :lang="entry.code"
-      :aria-label="entry.name"
-      :aria-current="entry.current ? 'page' : undefined"
-      class="inline-flex h-8 items-center gap-1.5 rounded px-2 text-xs font-medium transition-colors"
-      :class="
-        entry.current
-          ? 'bg-muted text-foreground'
-          : 'text-muted-foreground hover:bg-muted/60 hover:text-foreground'
-      "
-      @click="trackLocaleNavigation(entry)"
-    >
-      <Icon
-        v-if="entry.flagIcon"
-        :name="entry.flagIcon"
-        class="size-4 rounded-full"
-        aria-hidden="true"
-      />
-      <span>{{ entry.shortLabel }}</span>
-    </NuxtLink>
-  </div>
 </template>

package/app/components/site/SiteSocialLinks.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
-import { Button } from "#ginko-docs/components/ui/button";
 import { useSiteNavigation } from "#ginko-docs/composables/useSiteNavigation";
+import { headerUtilityButtonClass } from "#ginko-docs/components/site/header-utils";
 
 const { socialLinks } = useSiteNavigation();
 
@@ -9,23 +9,17 @@ defineEmits<{ navigate: [] }>();
 
 <template>
   <div v-if="socialLinks.length" class="flex items-center">
-    <Button
+    <NuxtLink
       v-for="link in socialLinks"
       :key="link.href"
-      as-child
-      variant="ghost"
-      size="icon"
-      class="text-muted-foreground hover:text-foreground"
+      :to="link.href"
+      target="_blank"
+      rel="noopener noreferrer"
+      :aria-label="link.label"
+      :class="headerUtilityButtonClass"
+      @click="$emit('navigate')"
     >
-      <NuxtLink
-        :to="link.href"
-        target="_blank"
-        rel="noopener noreferrer"
-        :aria-label="link.label"
-        @click="$emit('navigate')"
-      >
-        <Icon :name="link.icon ?? 'lucide:link'" class="size-[18px]" aria-hidden="true" />
-      </NuxtLink>
-    </Button>
+      <Icon :name="link.icon ?? 'lucide:link'" class="size-[18px]" aria-hidden="true" />
+    </NuxtLink>
   </div>
 </template>

package/app/components/site/header-utils.ts

@@ -0,0 +1,3 @@
+/** Shared ghost geometry for header utility controls (theme, locale, social). */
+export const headerUtilityButtonClass =
+  "inline-flex size-9 shrink-0 items-center justify-center rounded-lg text-muted-foreground transition-colors hover:bg-accent hover:text-foreground focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring outline-none";

package/app/components/site/mode-toggle.utils.ts

@@ -0,0 +1,18 @@
+export type RenderedColorMode = "light" | "dark";
+/**
+ * Next stored preference for a two-state theme toggle.
+ *
+ * The page follows the operating system until the first interaction. After
+ * that interaction, the reader's explicit light or dark choice remains fixed.
+ */
+export function nextColorModePreference(currentRendered: RenderedColorMode): RenderedColorMode {
+  return currentRendered === "dark" ? "light" : "dark";
+}
+
+export function themeToggleIcon(isDark: boolean) {
+  return isDark ? "lucide:moon" : "lucide:sun";
+}
+
+export function themeToggleLabelKey(isDark: boolean) {
+  return isDark ? "theme.switchToLight" : "theme.switchToDark";
+}

package/app/features/search/useCommandCenter.ts

@@ -1,7 +1,7 @@
 import { useLocalStorage } from "@vueuse/core";
 import { useContentSearch } from "@lupinum/ginko-content/client";
 import { computed, watch } from "vue";
-import { navigateTo, useI18n, useRoute, useState } from "#imports";
+import { navigateTo, useI18n, useState } from "#imports";
 import { useLocalizedPath } from "#ginko-docs/composables/useLocalizedPath";
 import { useSiteNavigation } from "#ginko-docs/composables/useSiteNavigation";
 import {
@@ -56,7 +56,6 @@ function flattenNavItems(items: DocsNavigationItem[]): DocsNavigationItem[] {
 }
 
 export async function useCommandCenter() {
-  const route = useRoute();
   const { locale, t } = useI18n();
   const localizedPath = useLocalizedPath();
   const {
@@ -279,13 +278,6 @@ export async function useCommandCenter() {
     searchQuery.value = value;
   });
 
-  watch(
-    () => route.fullPath,
-    () => {
-      closeCommandCenter();
-    },
-  );
-
   return {
     open,
     query,

package/app/plugins/ginko-docs-theme.ts

@@ -7,6 +7,7 @@ export default defineNuxtPlugin(() => {
     htmlAttrs: {
       "data-neutral": theme.neutral,
       "data-primary": theme.primary,
+      "data-code-blocks": theme.codeBlocks,
     },
   });
 });

package/i18n/messages/global/nav.ts

@@ -13,6 +13,11 @@ export const nav = {
   openMenu: { de: "Menü öffnen", en: "Open menu" },
   closeMenu: { de: "Menü schließen", en: "Close menu" },
   search: { de: "Suchen", en: "Search" },
+  searchDocumentation: {
+    de: "Dokumentation durchsuchen…",
+    en: "Search documentation…",
+  },
+  languageLabel: { de: "Sprache", en: "Language" },
   resources: { de: "Ressourcen", en: "Resources" },
   company: { de: "Unternehmen", en: "Company" },
   documentation: { de: "Dokumentation", en: "Documentation" },

package/i18n/messages/global/theme.ts

@@ -1,6 +1,8 @@
 export const theme = {
   label: { de: "Darstellung", en: "Appearance" },
   toggle: { de: "Darstellung umschalten", en: "Toggle theme" },
+  switchToDark: { de: "Zu Dunkelmodus wechseln", en: "Switch to dark mode" },
+  switchToLight: { de: "Zu Hellmodus wechseln", en: "Switch to light mode" },
   light: { de: "Hell", en: "Light" },
   dark: { de: "Dunkel", en: "Dark" },
   system: { de: "System", en: "System" },

package/icon-bundle.ts

@@ -4,6 +4,7 @@ export const layerIconNames = [
   "circle-flags:de",
   "circle-flags:us",
   "logos:bun",
+  "logos:discord-icon",
   "logos:npm-icon",
   "logos:nuxt-icon",
   "logos:pnpm",
@@ -52,6 +53,7 @@ export const layerIconNames = [
   "lucide:info",
   "lucide:lightbulb",
   "lucide:link",
+  "lucide:languages",
   "lucide:linkedin",
   "lucide:loader-circle",
   "lucide:list",

package/index.d.ts

@@ -1,4 +1,8 @@
 import type { GinkoDocsAppConfig } from "./shared/types/app-config";
+import type {
+  GinkoDocsNuxtConfig,
+  GinkoDocsSyntaxHighlightingConfig,
+} from "./shared/types/nuxt-config";
 
 type GinkoDocsAppConfigInput<T> = T extends readonly unknown[]
   ? T
@@ -14,6 +18,20 @@ declare module "nuxt/schema" {
   interface AppConfigInput {
     ginkoDocs?: GinkoDocsAppConfigInput<GinkoDocsAppConfig>;
   }
+
+  interface NuxtConfig {
+    ginkoDocs?: GinkoDocsNuxtConfig;
+  }
+
+  interface NuxtOptions {
+    ginkoDocs?: GinkoDocsNuxtConfig;
+  }
+
+  interface PublicRuntimeConfig {
+    ginkoDocs?: {
+      syntaxHighlighting?: GinkoDocsSyntaxHighlightingConfig;
+    };
+  }
 }
 
 export {};

package/modules/syntax-highlighting.ts

@@ -0,0 +1,120 @@
+import { defineNuxtModule } from "@nuxt/kit";
+import { bundledThemes } from "shiki";
+import type { BundledTheme } from "shiki";
+import type {
+  GinkoDocsSyntaxHighlightingConfig,
+  GinkoDocsNuxtConfig,
+} from "../shared/types/nuxt-config";
+
+export const DEFAULT_SYNTAX_THEMES = {
+  light: "light-plus",
+  dark: "dark-plus",
+} as const satisfies GinkoDocsSyntaxHighlightingConfig["themes"];
+
+type ShikiPluginOptions = {
+  preStyles?: boolean;
+  transformers?: unknown[];
+  themes?: { light: unknown; dark: unknown };
+};
+
+type MarkdownPlugin = string | [string, Record<string, unknown>?];
+
+export async function resolveBundledTheme(name: string, configPath: string) {
+  const loader = bundledThemes[name as BundledTheme];
+  if (!loader) {
+    throw new Error(
+      `Invalid Ginko Docs syntax theme "${name}".\n\nExpected a bundled Shiki theme name at:\n${configPath}`,
+    );
+  }
+
+  const mod = await loader();
+  return mod.default ?? mod;
+}
+
+export function findShikiPlugin(plugins: MarkdownPlugin[]) {
+  for (let index = 0; index < plugins.length; index += 1) {
+    const plugin = plugins[index];
+    if (plugin === "shiki") {
+      return { index, options: {} as ShikiPluginOptions };
+    }
+    if (Array.isArray(plugin) && plugin[0] === "shiki") {
+      return { index, options: (plugin[1] ?? {}) as ShikiPluginOptions };
+    }
+  }
+  return null;
+}
+
+export function countShikiPlugins(plugins: MarkdownPlugin[]) {
+  return plugins.filter(
+    (plugin) => plugin === "shiki" || (Array.isArray(plugin) && plugin[0] === "shiki"),
+  ).length;
+}
+
+export async function patchShikiThemes(
+  plugins: MarkdownPlugin[],
+  themes: GinkoDocsSyntaxHighlightingConfig["themes"],
+) {
+  const shiki = findShikiPlugin(plugins);
+  if (!shiki) {
+    throw new Error("Ginko Docs could not locate the Shiki Markdown plugin to patch.");
+  }
+
+  const [light, dark] = await Promise.all([
+    resolveBundledTheme(themes.light, "ginkoDocs.syntaxHighlighting.themes.light"),
+    resolveBundledTheme(themes.dark, "ginkoDocs.syntaxHighlighting.themes.dark"),
+  ]);
+
+  shiki.options.themes = { light, dark };
+
+  const plugin = plugins[shiki.index];
+  if (Array.isArray(plugin)) {
+    plugin[1] = shiki.options;
+  } else {
+    plugins[shiki.index] = ["shiki", shiki.options];
+  }
+}
+
+export function mergeSyntaxRuntimeConfig(
+  current: Record<string, unknown> | undefined,
+  themes: GinkoDocsSyntaxHighlightingConfig["themes"],
+) {
+  return {
+    ...current,
+    syntaxHighlighting: {
+      themes: {
+        light: themes.light,
+        dark: themes.dark,
+      },
+    },
+  };
+}
+
+export default defineNuxtModule<GinkoDocsNuxtConfig>({
+  meta: {
+    name: "ginko-docs-syntax-highlighting",
+    configKey: "ginkoDocs",
+  },
+  async setup(options, nuxt) {
+    const themes = options.syntaxHighlighting?.themes ?? DEFAULT_SYNTAX_THEMES;
+
+    nuxt.options.runtimeConfig.public.ginkoDocs = mergeSyntaxRuntimeConfig(
+      nuxt.options.runtimeConfig.public.ginkoDocs,
+      themes,
+    );
+
+    if (!options.syntaxHighlighting) return;
+
+    const content = nuxt.options.content;
+    if (!content) {
+      throw new Error("Ginko Docs could not locate the content module configuration.");
+    }
+
+    content.markdown ??= {};
+    content.markdown.plugins ??= [];
+
+    await patchShikiThemes(
+      content.markdown.plugins as MarkdownPlugin[],
+      options.syntaxHighlighting.themes,
+    );
+  },
+});

package/nuxt.config.ts

@@ -34,6 +34,7 @@ export default defineNuxtConfig({
   alias: { "#ginko-docs": app },
   css: [join(app, "assets/css/tailwind.css"), join(app, "assets/css/prose.css")],
   modules: [
+    join(root, "modules/syntax-highlighting"),
     join(root, "modules/feature-routing"),
     "@nuxt/icon",
     "@nuxt/fonts",
@@ -55,7 +56,7 @@ export default defineNuxtConfig({
   },
   mcp: {
     name: "Ginko Docs",
-    version: "0.3.0-rc.5",
+    version: "0.3.0",
   },
   components: {
     dirs: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lupinum/ginko-docs",
-  "version": "0.3.0-rc.5",
+  "version": "0.3.0",
   "description": "A Nuxt documentation layer powered by Ginko Content.",
   "keywords": [
     "content",
@@ -48,7 +48,8 @@
       "default": "./content.js"
     },
     "./app-config": "./shared/types/app-config.ts",
-    "./components": "./components.ts"
+    "./components": "./components.ts",
+    "./nuxt-config": "./shared/types/nuxt-config.ts"
   },
   "publishConfig": {
     "access": "public"

package/shared/types/app-config.ts

@@ -4,6 +4,7 @@ import type { GinkoDocsNeutralPalette, GinkoDocsPrimaryPalette } from "../theme-
 export type GinkoDocsLocalizedText = string | { en: string; de?: string };
 
 export type GinkoDocsProseAppearance = "quiet" | "tint";
+export type GinkoDocsCodeBlockTheme = "dark" | "adaptive";
 export type GinkoDocsProseFamily =
   | "callout"
   | "aside"
@@ -62,6 +63,7 @@ export interface GinkoDocsAppConfig {
   theme: {
     neutral: GinkoDocsNeutralPalette;
     primary: GinkoDocsPrimaryPalette;
+    codeBlocks: GinkoDocsCodeBlockTheme;
   };
   prose: GinkoDocsProseConfig;
   site: {

package/shared/types/nuxt-config.ts

@@ -0,0 +1,14 @@
+import type { BundledTheme } from "shiki";
+
+export type GinkoDocsSyntaxTheme = BundledTheme;
+
+export interface GinkoDocsSyntaxHighlightingConfig {
+  themes: {
+    light: GinkoDocsSyntaxTheme;
+    dark: GinkoDocsSyntaxTheme;
+  };
+}
+
+export interface GinkoDocsNuxtConfig {
+  syntaxHighlighting?: GinkoDocsSyntaxHighlightingConfig;
+}