@lupinum/ginko-docs 0.2.2

package/app/composables/useLocalizedRouteSwitch.ts

@@ -0,0 +1,31 @@
+import { useRoute, useSwitchLocalePath } from "#imports";
+import type { RouteLocationRaw } from "vue-router";
+import { useContentRouteAlternates } from "./useContentRouteAlternates";
+import { isLocaleCode } from "../../i18n/locales";
+
+export function useLocalizedRouteSwitch() {
+  const route = useRoute();
+  const switchLocalePath = useSwitchLocalePath();
+  const alternates = useContentRouteAlternates();
+
+  function switchPathname(targetLocale: string) {
+    if (!isLocaleCode(targetLocale)) {
+      return route.path;
+    }
+
+    const configuredLocale = targetLocale as Parameters<typeof switchLocalePath>[0];
+    return (
+      alternates.value.find((alternate) => alternate.locale === targetLocale)?.path ||
+      switchLocalePath(configuredLocale)
+    );
+  }
+
+  function switchPath(targetLocale: string): RouteLocationRaw {
+    return { path: switchPathname(targetLocale), query: route.query, hash: route.hash };
+  }
+
+  return {
+    switchPath,
+    switchPathname,
+  };
+}

package/app/composables/usePageMarkdownActions.ts

@@ -0,0 +1,79 @@
+import { agentRawPathForRoute } from "@lupinum/ginko-content/agent-paths";
+import { useClipboard } from "@vueuse/core";
+import { computed, onBeforeUnmount, ref } from "vue";
+import { useRoute } from "#imports";
+import { useGinkoDocsConfig } from "./useGinkoDocsConfig";
+
+export type PageMarkdownAction = "markdown" | "link" | "mcp";
+export type PageMarkdownActionResult = "success" | "error";
+
+export function usePageMarkdownActions() {
+  const route = useRoute();
+  const config = useGinkoDocsConfig();
+  const { copy } = useClipboard({ legacy: true });
+  const result = ref<{ action: PageMarkdownAction; status: PageMarkdownActionResult } | null>(null);
+  let resetTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const rawPath = computed(() => agentRawPathForRoute(route.path));
+  const rawUrl = computed(() => new URL(rawPath.value, config.site.url).toString());
+  const mcpUrl = computed(() => new URL("/mcp", config.site.url).toString());
+  const chatGptUrl = computed(
+    () =>
+      `https://chatgpt.com/?hints=search&q=${encodeURIComponent(`Read ${rawUrl.value} so I can ask questions about it.`)}`,
+  );
+  const claudeUrl = computed(
+    () =>
+      `https://claude.ai/new?q=${encodeURIComponent(`Read ${rawUrl.value} so I can ask questions about it.`)}`,
+  );
+  const actions = computed(() => ({
+    chatGpt: config.markdownActions?.chatGpt !== false,
+    claude: config.markdownActions?.claude !== false,
+    mcp: config.markdownActions?.mcp !== false,
+  }));
+
+  function setResult(action: PageMarkdownAction, status: PageMarkdownActionResult) {
+    if (resetTimer) clearTimeout(resetTimer);
+    result.value = { action, status };
+    resetTimer = setTimeout(
+      () => {
+        result.value = null;
+      },
+      status === "success" ? 1800 : 4000,
+    );
+  }
+
+  async function run(action: PageMarkdownAction, operation: () => Promise<void>) {
+    try {
+      await operation();
+      setResult(action, "success");
+    } catch {
+      setResult(action, "error");
+    }
+  }
+
+  const copyValue = (value: string, action: Exclude<PageMarkdownAction, "markdown">) =>
+    run(action, () => copy(value));
+
+  const copyMarkdown = () =>
+    run("markdown", async () => {
+      const response = await fetch(rawPath.value);
+      if (!response.ok) throw new Error(`Markdown request failed with ${response.status}`);
+      await copy(await response.text());
+    });
+
+  onBeforeUnmount(() => {
+    if (resetTimer) clearTimeout(resetTimer);
+  });
+
+  return {
+    actions,
+    chatGptUrl,
+    claudeUrl,
+    copyMarkdown,
+    copyValue,
+    mcpUrl,
+    rawPath,
+    rawUrl,
+    result,
+  };
+}

package/app/composables/useSchemaJsonLd.ts

@@ -0,0 +1,25 @@
+import { toValue, type MaybeRefOrGetter } from "vue";
+import { useHead } from "#imports";
+
+export type SchemaJsonNode = Record<string, unknown>;
+
+export function useSchemaJsonLd(schemas: MaybeRefOrGetter<SchemaJsonNode[]>) {
+  useHead(() => {
+    const graph = toValue(schemas).filter(Boolean);
+
+    return {
+      script: graph.length
+        ? [
+            {
+              type: "application/ld+json",
+              "data-schema-org": "true",
+              innerHTML: JSON.stringify({
+                "@context": "https://schema.org",
+                "@graph": graph,
+              }),
+            },
+          ]
+        : [],
+    };
+  });
+}

package/app/composables/useSiteNavigation.ts

@@ -0,0 +1,86 @@
+import { getLocalizedSiteText } from "#ginko-docs/config/site.utils";
+import { useI18n, useRouter } from "#imports";
+import { useLocalizedPath } from "#ginko-docs/composables/useLocalizedPath";
+import { computed } from "vue";
+import { useGinkoDocsConfig } from "./useGinkoDocsConfig";
+import { resolveBanner, resolveMainNav, type NavItem } from "./site-navigation.utils";
+
+export interface SidebarSection {
+  title: string;
+  items: { label: string; href: string; badge?: string }[];
+}
+
+export const useSiteNavigation = () => {
+  const config = useGinkoDocsConfig();
+  const { locale, t } = useI18n();
+  const router = useRouter();
+  const path = useLocalizedPath();
+
+  const site = computed(() => ({
+    name: getLocalizedSiteText(config.site.name, locale.value),
+    description: getLocalizedSiteText(config.site.description, locale.value),
+    logo: config.site.logo,
+    url: config.site.url,
+    lupinumAttribution: config.site.lupinumAttribution,
+  }));
+
+  const blogPath = computed(() => path("blog"));
+  const blogExists = computed(() =>
+    router.getRoutes().some((route) => route.path === blogPath.value),
+  );
+
+  const banner = computed(() =>
+    resolveBanner(config.banner, {
+      locale: locale.value,
+      blogPath: blogPath.value,
+      blogExists: blogExists.value,
+      defaultText: t("banner.text"),
+      defaultLinkLabel: t("banner.linkLabel"),
+    }),
+  );
+
+  const socialLinks = computed<NavItem[]>(
+    () =>
+      [
+        config.social.github
+          ? {
+              label: t("nav.github"),
+              href: config.social.github,
+              external: true,
+              icon: "lucide:github",
+            }
+          : null,
+        config.social.linkedin
+          ? {
+              label: "LinkedIn",
+              href: config.social.linkedin,
+              external: true,
+              icon: "lucide:linkedin",
+            }
+          : null,
+      ].filter(Boolean) as NavItem[],
+  );
+
+  const mainNav = computed<NavItem[]>(() =>
+    resolveMainNav(config.nav.links, {
+      locale: locale.value,
+      docsPath: path("docs"),
+      blogPath: blogPath.value,
+      blogExists: blogExists.value,
+      docsLabel: t("nav.documentation"),
+      blogLabel: t("nav.blog"),
+    }),
+  );
+
+  const footerNav = computed<{
+    product: NavItem[];
+    resources: NavItem[];
+    company: NavItem[];
+  }>(() => ({
+    product: [],
+    resources: [...socialLinks.value],
+    company: [],
+  }));
+
+  return { site, banner, mainNav, footerNav, socialLinks };
+};

package/app/config/site.utils.ts

@@ -0,0 +1,36 @@
+import type { GinkoDocsLocalizedText } from "../../shared/types/app-config";
+import { defaultLocale, type LocaleCode } from "../../i18n/locales";
+
+export function getLocalizedSiteText(
+  value: GinkoDocsLocalizedText | string,
+  locale: string,
+  fallbackLocale: LocaleCode = defaultLocale,
+): string {
+  if (typeof value === "string") return value;
+  return value[locale as LocaleCode] ?? value[fallbackLocale] ?? Object.values(value)[0] ?? "";
+}
+
+function isLocalSiteUrl(value: string) {
+  try {
+    const host = new URL(value).hostname;
+    return host === "localhost" || host === "127.0.0.1" || host === "::1";
+  } catch {
+    return false;
+  }
+}
+
+export function resolveSiteUrl(
+  canonicalUrl: string,
+  options: {
+    envUrl?: string;
+    mode?: string;
+  } = {},
+) {
+  const { envUrl, mode } = options;
+
+  if (!envUrl) return canonicalUrl;
+  if (isLocalSiteUrl(envUrl) && mode !== "development" && mode !== "test") {
+    return canonicalUrl;
+  }
+  return envUrl;
+}

package/app/error.vue

@@ -0,0 +1,125 @@
+<script setup lang="ts">
+import { localizedRoutes } from "../i18n/routes";
+import { messages } from "../i18n/messages/index";
+import { normalizeAppError } from "./lib/errors";
+import { computed } from "vue";
+import { clearError, useHead } from "#imports";
+import { useDocsEntryPath } from "#ginko-docs/features/docs/composables/useDocsEntryPath";
+import { localeFromPath, localizedPath } from "../i18n/locales";
+
+type NuxtErrorLike = {
+  message?: string;
+  status?: number;
+  statusCode?: number;
+  statusMessage?: string;
+  statusText?: string;
+  url?: string;
+};
+
+const props = defineProps<{
+  error: NuxtErrorLike;
+}>();
+
+const normalized = computed(() => normalizeAppError(props.error));
+const requestPath = computed(
+  () => props.error?.url || (import.meta.client ? window.location.pathname : "/"),
+);
+const locale = computed(() => localeFromPath(requestPath.value));
+const copy = computed(() => {
+  const catalog = messages[locale.value].errors;
+  return catalog[normalized.value.kind] ?? catalog.unavailable;
+});
+const docsPath = await useDocsEntryPath();
+const homePath = computed(() => localizedPath(locale.value, localizedRoutes[locale.value].home));
+const title = computed(() => `${normalized.value.statusCode} - ${copy.value.title}`);
+// Keep the full site chrome for content-level errors (404 and friends); hard
+// server failures fall back to the bare page so the error screen cannot crash.
+const showChrome = computed(() => normalized.value.kind !== "server");
+
+useHead(() => ({
+  title: title.value,
+  meta: [{ name: "robots", content: "noindex, nofollow" }],
+}));
+
+const handleError = () => clearError({ redirect: homePath.value });
+</script>
+
+<template>
+  <div class="flex min-h-dvh flex-col bg-background text-foreground">
+    <template v-if="showChrome">
+      <SiteSkipLink />
+      <SiteHeader />
+    </template>
+    <main id="main-content" class="flex flex-1 items-center justify-center px-4 py-24">
+      <section class="w-full max-w-xl text-center">
+        <p
+          class="mb-6 text-8xl leading-none font-bold text-primary/20 select-none"
+          aria-hidden="true"
+        >
+          {{ normalized.statusCode }}
+        </p>
+
+        <p class="mb-3 text-sm font-medium tracking-wider text-primary uppercase">
+          {{ normalized.statusMessage }}
+        </p>
+        <h1 class="mb-4 text-3xl font-semibold tracking-tight text-foreground sm:text-4xl">
+          {{ copy.title }}
+        </h1>
+        <p class="mx-auto mb-8 max-w-md leading-7 text-muted-foreground">
+          {{ copy.description }}
+        </p>
+
+        <div class="flex flex-col items-center justify-center gap-3 sm:flex-row">
+          <button class="error-action error-action-primary" type="button" @click="handleError">
+            {{ messages[locale].errors.actions.home }}
+          </button>
+          <a class="error-action error-action-secondary" :href="docsPath">
+            {{ messages[locale].errors.actions.docs }}
+          </a>
+        </div>
+      </section>
+    </main>
+    <SiteFooter v-if="showChrome" />
+  </div>
+</template>
+
+<style scoped>
+.error-action {
+  align-items: center;
+  border-radius: 0.375rem;
+  display: inline-flex;
+  font-size: 0.875rem;
+  font-weight: 500;
+  height: 2.5rem;
+  justify-content: center;
+  padding-inline: 1rem;
+  transition:
+    background-color 150ms,
+    color 150ms,
+    border-color 150ms;
+}
+
+.error-action:focus-visible {
+  outline: 2px solid var(--ring);
+  outline-offset: 2px;
+}
+
+.error-action-primary {
+  background: var(--primary);
+  color: var(--primary-foreground);
+}
+
+.error-action-primary:hover {
+  opacity: 0.9;
+}
+
+.error-action-secondary {
+  background: var(--background);
+  border: 1px solid var(--input);
+}
+
+.error-action-secondary:hover {
+  background: var(--accent);
+  color: var(--accent-foreground);
+}
+</style>

package/app/features/docs/components/DocsContributeLinks.vue

@@ -0,0 +1,65 @@
+<script setup lang="ts">
+import type { GinkoDocsAppConfig } from "../../../../shared/types/app-config";
+import { computed } from "vue";
+import { useAppConfig, useI18n, useRoute } from "#imports";
+
+const props = defineProps<{
+  stem?: string;
+  extension?: string;
+  title: string;
+}>();
+
+const route = useRoute();
+const { t } = useI18n();
+const repository = (useAppConfig().ginkoDocs as GinkoDocsAppConfig).repository;
+
+const sourcePath = computed(() => {
+  if (!repository || !props.stem) return null;
+  const directory = repository.contentDirectory?.replace(/^\/+|\/+$/g, "") ?? "content";
+  const extension = props.extension?.replace(/^\./, "") || "md";
+  return `${directory}/${props.stem}.${extension}`;
+});
+
+const editUrl = computed(() => {
+  if (!repository || !sourcePath.value) return null;
+  const branch = repository.branch || "main";
+  return `${repository.url.replace(/\/$/, "")}/edit/${encodeURIComponent(branch)}/${sourcePath.value}`;
+});
+
+const issueUrl = computed(() => {
+  if (!repository) return null;
+  const url = new URL(`${repository.url.replace(/\/$/, "")}/issues/new`);
+  url.searchParams.set("title", t("docs.issueTitle", { title: props.title }));
+  url.searchParams.set("body", t("docs.issueBody", { path: route.path }));
+  return url.toString();
+});
+</script>
+
+<template>
+  <div
+    v-if="repository"
+    class="mt-12 flex flex-wrap items-center gap-x-4 gap-y-2 border-t border-border pt-5 text-sm"
+    :aria-label="t('docs.contribute')"
+  >
+    <a
+      v-if="editUrl"
+      :href="editUrl"
+      target="_blank"
+      rel="noopener noreferrer"
+      class="inline-flex min-h-9 items-center gap-1.5 font-medium text-muted-foreground transition-colors hover:text-foreground focus-visible:rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+    >
+      <Icon name="lucide:pen-line" class="size-4" aria-hidden="true" />
+      {{ t("docs.editPage") }}
+    </a>
+    <a
+      v-if="issueUrl"
+      :href="issueUrl"
+      target="_blank"
+      rel="noopener noreferrer"
+      class="inline-flex min-h-9 items-center gap-1.5 font-medium text-muted-foreground transition-colors hover:text-foreground focus-visible:rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+    >
+      <Icon name="lucide:circle-alert" class="size-4" aria-hidden="true" />
+      {{ t("docs.reportIssue") }}
+    </a>
+  </div>
+</template>

package/app/features/docs/components/DocsMobileToc.vue

@@ -0,0 +1,104 @@
+<script setup lang="ts">
+import type { HTMLAttributes } from "vue";
+import { ref, watch } from "vue";
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetTitle,
+  SheetTrigger,
+} from "#ginko-docs/components/ui/sheet";
+import { cn } from "#ginko-docs/lib/utils";
+import type { TocItem } from "./DocsToc.vue";
+import DocsToc from "./DocsToc.vue";
+import { useI18n, useRoute } from "#imports";
+
+const props = defineProps<{
+  items: TocItem[];
+  activeId?: string;
+  pageTitle?: string;
+  class?: HTMLAttributes["class"];
+}>();
+
+const sidebarOpen = ref(false);
+const tocOpen = ref(false);
+const route = useRoute();
+const { t } = useI18n();
+
+watch(
+  () => route.hash,
+  () => {
+    tocOpen.value = false;
+  },
+);
+watch(
+  () => route.path,
+  () => {
+    sidebarOpen.value = false;
+    tocOpen.value = false;
+  },
+);
+</script>
+
+<template>
+  <div
+    :class="
+      cn(
+        'sticky top-[var(--site-header-height)] z-30 flex h-11 shrink-0 items-center justify-between border-b border-border bg-background/90 px-4 backdrop-blur-md md:px-6 xl:hidden',
+        props.class,
+      )
+    "
+  >
+    <Sheet v-model:open="sidebarOpen">
+      <SheetTrigger as-child>
+        <button
+          type="button"
+          class="-ml-1 flex h-8 min-w-0 items-center gap-2 rounded-lg px-2 text-sm font-medium text-foreground transition-colors hover:bg-muted"
+          :aria-label="t('docs.pageNavigation')"
+        >
+          <Icon
+            name="lucide:panel-left-open"
+            class="size-4 shrink-0 text-muted-foreground"
+            aria-hidden="true"
+          />
+          <span class="truncate">{{ pageTitle ?? t("docs.fallbackTitle") }}</span>
+        </button>
+      </SheetTrigger>
+
+      <SheetContent side="left" class="flex w-[20rem] max-w-[86vw] flex-col gap-0 p-0">
+        <div class="border-b border-border px-4 py-3">
+          <SheetTitle class="text-sm font-semibold">{{ t("docs.label") }}</SheetTitle>
+          <SheetDescription class="sr-only">{{ t("docs.pageNavigation") }}</SheetDescription>
+        </div>
+        <div class="min-h-0 flex-1">
+          <DocsSidebar variant="drawer" />
+        </div>
+      </SheetContent>
+    </Sheet>
+
+    <Sheet v-if="items.length" v-model:open="tocOpen">
+      <SheetTrigger as-child>
+        <button
+          class="-mr-1 flex h-7 shrink-0 items-center gap-1.5 rounded-md px-2.5 text-xs font-medium text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+        >
+          <Icon name="lucide:list" class="size-3.5" aria-hidden="true" />
+          <span>{{ t("docs.toc") }}</span>
+        </button>
+      </SheetTrigger>
+
+      <SheetContent side="bottom" class="flex max-h-[85dvh] flex-col gap-0 rounded-t-2xl p-0">
+        <div class="flex shrink-0 flex-col items-center border-b border-border px-6 pt-3 pb-4">
+          <div class="mb-4 h-1 w-10 rounded-full bg-border" />
+          <SheetTitle class="self-start text-sm font-semibold">{{ t("docs.toc") }}</SheetTitle>
+          <SheetDescription class="sr-only">{{
+            pageTitle ?? t("docs.fallbackTitle")
+          }}</SheetDescription>
+        </div>
+
+        <div class="flex-1 overflow-y-auto px-6 py-5" @click="tocOpen = false">
+          <DocsToc :items="items" :active-id="activeId" :show-title="false" />
+        </div>
+      </SheetContent>
+    </Sheet>
+  </div>
+</template>