@lupinum/ginko-docs 0.2.2 → 0.2.5

package/app/features/search/useCommandCenter.ts

@@ -8,10 +8,8 @@ import {
   getDocsNavigationGroups,
   type DocsNavigationItem,
 } from "#ginko-docs/features/docs/docs-navigation";
-import { useDocsEntryPath } from "#ginko-docs/features/docs/composables/useDocsEntryPath";
 import { useDocsNavigation } from "#ginko-docs/features/docs/composables/useDocsNavigation";
 import {
-  contentSearchGroup,
   dedupeCommandCenterItems,
   groupCommandCenterItems,
   PAGE_HIGHLIGHT_STORAGE_KEY,
@@ -21,14 +19,6 @@ import {
   type StoredRecentItem,
 } from "#ginko-docs/features/search/command-center";
 
-type ContentSearchHit = {
-  collection: string;
-  path: string;
-  title: string;
-  excerpt?: string;
-  anchor?: string;
-};
-
 const MAX_DEFAULT_PAGE_ITEMS = 6;
 const MAX_DEFAULT_DOC_ITEMS = 3;
 
@@ -77,21 +67,27 @@ export async function useCommandCenter() {
   } = useCommandCenterState();
   const recentSelections = useLocalStorage<StoredRecentItem[]>("site-command-center-recent", []);
 
-  const { mainNav, footerNav, socialLinks } = useSiteNavigation();
+  const { mainNav, socialLinks } = useSiteNavigation();
   // Start every context-bound composable before the first await. Calling a
   // Nuxt/i18n composable after an awaited operation loses the setup context.
-  const docsEntryPathResult = useDocsEntryPath();
   const docsNavigationResult = useDocsNavigation();
   const contentSearchResult = useContentSearch({
     limit: 12,
     locale: () => locale.value,
   });
-  const [docsEntryPath, { sections }, { query: searchQuery, results: searchResults }] =
-    await Promise.all([docsEntryPathResult, docsNavigationResult, contentSearchResult]);
+  const [
+    { sections },
+    {
+      query: searchQuery,
+      results: searchResults,
+      pending: searchPending,
+      error: searchError,
+      isEmpty: searchIsEmpty,
+    },
+  ] = await Promise.all([docsNavigationResult, contentSearchResult]);
 
   const contentSearchItems = computed<CommandCenterItem[]>(() =>
-    searchResults.value.map((hit: ContentSearchHit) => {
-      const group = contentSearchGroup(hit.collection);
+    searchResults.value.map((hit) => {
       const href = hit.anchor ? `${hit.path}#${hit.anchor}` : hit.path;
 
       return {
@@ -99,10 +95,9 @@ export async function useCommandCenter() {
         title: hit.title,
         subtitle: hit.excerpt,
         href,
-        group,
-        icon: group === "blog" ? "lucide:newspaper" : "lucide:book-open",
-        keywords: [group, hit.title, hit.excerpt ?? ""],
-        badge: group === "blog" ? t("nav.blog") : t("docs.label"),
+        group: "search",
+        icon: hit.collection === "blog" ? "lucide:newspaper" : "lucide:book-open",
+        badge: hit.collection === "blog" ? t("nav.blog") : t("docs.label"),
       };
     }),
   );
@@ -130,11 +125,10 @@ export async function useCommandCenter() {
       keywords: ["navigation", item.label],
     }));
 
-    const footerResources = [
-      { label: t("nav.documentation"), href: docsEntryPath.value },
-      ...footerNav.value.resources,
-    ];
-    const fromFooter = [...footerNav.value.product, ...footerResources, ...footerNav.value.company]
+    const fromFooter = [
+      { label: t("nav.documentation"), href: localizedPath("docs") },
+      ...socialLinks.value,
+    ]
       .filter((item) => !(item as { external?: boolean }).external)
       .map<CommandCenterItem>((item) => ({
         id: `page-footer-${item.href}`,
@@ -175,7 +169,7 @@ export async function useCommandCenter() {
               title: section.title,
               subtitle: t("command.pages.documentation"),
               href: section.path,
-              group: "docs",
+              group: "docs_nav",
               icon: section.icon ?? "lucide:book-open",
               keywords: [section.title],
             },
@@ -187,7 +181,7 @@ export async function useCommandCenter() {
   });
 
   const actionItems = computed<CommandCenterItem[]>(() => {
-    const github = socialLinks.value.find((item) => item.icon === "lucide:github");
+    const github = socialLinks.value.find((item) => item.platform === "github");
     return github
       ? [
           {
@@ -197,37 +191,26 @@ export async function useCommandCenter() {
             href: github.href,
             external: true,
             group: "actions" as const,
-            icon: "lucide:github",
+            icon: github.icon ?? "lucide:github",
             keywords: ["repo", "source", "code"],
           },
         ]
       : [];
   });
 
-  // Cross-group dedupe: a page reachable via nav can also appear as a content
-  // search hit with the same href. First occurrence wins, so nav entries
-  // (higher group priority) shadow duplicate search results while anchored
-  // hits (#section) stay distinct.
-  const allItems = computed(() =>
-    dedupeCommandCenterItems([
-      ...pageItems.value,
-      ...docsItems.value,
-      ...contentSearchItems.value,
-      ...actionItems.value,
-    ]),
+  const canonicalItems = computed(() =>
+    dedupeCommandCenterItems([...pageItems.value, ...docsItems.value, ...actionItems.value]),
   );
 
   const recentItems = computed<CommandCenterItem[]>(() => {
     if (query.value) return [];
 
-    return resolveRecentItems(recentSelections.value, allItems.value);
+    return resolveRecentItems(recentSelections.value, canonicalItems.value);
   });
 
   const defaultItems = computed<CommandCenterItem[]>(() => {
     const recentSourceIds = new Set(recentItems.value.map((item) => item.sourceId));
-    const docSectionItems = docsItems.value
-      .filter((item) => item.id.startsWith("doc-switcher-"))
-      .slice(0, MAX_DEFAULT_DOC_ITEMS);
+    const docSectionItems = docsItems.value.slice(0, MAX_DEFAULT_DOC_ITEMS);
 
     return dedupeCommandCenterItems([
       ...pageItems.value.slice(0, MAX_DEFAULT_PAGE_ITEMS),
@@ -237,16 +220,30 @@ export async function useCommandCenter() {
   });
 
   const groupedItems = computed(() => {
-    const candidates = query.value.trim()
-      ? allItems.value
-      : [...recentItems.value, ...defaultItems.value];
-    return groupCommandCenterItems(candidates, query.value, (group) =>
+    if (query.value.trim()) {
+      return contentSearchItems.value.length
+        ? [
+            {
+              id: "search" as const,
+              title: t("command.groups.search"),
+              items: contentSearchItems.value,
+            },
+          ]
+        : [];
+    }
+    return groupCommandCenterItems([...recentItems.value, ...defaultItems.value], (group) =>
       t(`command.groups.${group}`),
     );
   });
 
   function rememberSelection(item: CommandCenterItem) {
-    recentSelections.value = rememberRecentItem(item, recentSelections.value);
+    const canonicalItem =
+      item.group === "search"
+        ? canonicalItems.value.find((candidate) => candidate.href === item.href)
+        : item;
+    if (canonicalItem) {
+      recentSelections.value = rememberRecentItem(canonicalItem, recentSelections.value);
+    }
   }
 
   function closeCommandCenter() {
@@ -293,6 +290,9 @@ export async function useCommandCenter() {
     open,
     query,
     groupedItems,
+    searchPending,
+    searchError,
+    searchIsEmpty,
     openCommandCenter,
     closeCommandCenter,
     selectItem,

package/app/layouts/docs.vue

@@ -6,7 +6,7 @@
 
     <div class="mx-auto flex w-full max-w-screen-2xl min-w-0 flex-1">
       <div
-        class="pointer-events-none sticky top-[var(--site-header-height)] z-20 hidden h-[calc(100dvh-var(--site-header-height))] w-[var(--docs-sidebar-width)] shrink-0 overflow-hidden *:pointer-events-auto md:block"
+        class="pointer-events-none sticky top-[var(--site-header-height)] z-20 hidden h-[calc(100dvh-var(--site-header-height)-var(--site-banner-height,0px))] w-[var(--docs-sidebar-width)] shrink-0 overflow-hidden *:pointer-events-auto md:block"
       >
         <DocsSidebar />
       </div>

package/app/lib/errors.ts

@@ -2,31 +2,12 @@ export type ErrorKind = "accessDenied" | "notFound" | "server" | "unavailable";
 
 export interface NormalizedAppError {
   kind: ErrorKind;
-  message: string;
   statusCode: number;
-  statusMessage: string;
 }
 
 type ErrorLike = {
-  data?: unknown;
-  fatal?: boolean;
-  message?: string;
-  name?: string;
   status?: number;
   statusCode?: number;
-  statusMessage?: string;
-  statusText?: string;
-};
-
-type ContentNotFoundError = Error & {
-  data: {
-    kind: "content-not-found";
-  };
-  fatal: true;
-  status: 404;
-  statusCode: 404;
-  statusMessage: "Not Found";
-  statusText: "Not Found";
 };
 
 function isObject(value: unknown): value is Record<string, unknown> {
@@ -44,41 +25,13 @@ function toStatusCode(error: ErrorLike): number {
 
 function errorKind(statusCode: number): ErrorKind {
   if (statusCode === 404) return "notFound";
-  if (statusCode === 403) return "accessDenied";
+  if (statusCode === 401 || statusCode === 403) return "accessDenied";
   if (statusCode >= 500) return "server";
   return "unavailable";
 }
 
-function defaultStatusMessage(statusCode: number, kind: ErrorKind): string {
-  if (kind === "notFound") return "Not Found";
-  if (kind === "accessDenied") return "Forbidden";
-  if (kind === "server") return "Internal Server Error";
-  return statusCode >= 400 ? "Unavailable" : "Error";
-}
-
 export function normalizeAppError(error: unknown): NormalizedAppError {
   const source = toErrorLike(error);
   const statusCode = toStatusCode(source);
-  const kind = errorKind(statusCode);
-  const statusMessage =
-    source.statusMessage ?? source.statusText ?? defaultStatusMessage(statusCode, kind);
-  const message = source.message ?? statusMessage;
-
-  return {
-    kind,
-    message,
-    statusCode,
-    statusMessage,
-  };
-}
-
-export function createContentNotFoundError(): ContentNotFoundError {
-  const error = new Error("Content not found") as ContentNotFoundError;
-  error.data = { kind: "content-not-found" };
-  error.fatal = true;
-  error.status = 404;
-  error.statusCode = 404;
-  error.statusMessage = "Not Found";
-  error.statusText = "Not Found";
-  return error;
+  return { kind: errorKind(statusCode), statusCode };
 }

package/app/pages/blog/[slug].vue

@@ -2,13 +2,18 @@
 import { Badge } from "#ginko-docs/components/ui/badge";
 import ContentFeedback from "#ginko-docs/components/content/Feedback.vue";
 import { Button } from "#ginko-docs/components/ui/button";
-import { createContentNotFoundError } from "#ginko-docs/lib/errors";
 import { createArticleSchema, createBreadcrumbSchema } from "#ginko-docs/lib/schema-org";
 import { getLocalizedSiteText } from "#ginko-docs/config/site.utils";
-import { filterTocByDepth, flattenTocLinks, formatContentDate } from "#ginko-docs/utils/content";
+import {
+  filterTocByDepth,
+  flattenTocLinks,
+  formatContentDate,
+  getMarkdownTocLinks,
+} from "#ginko-docs/utils/content";
 import { computed, watch } from "vue";
 import {
   definePageMeta,
+  createError,
   useAppConfig,
   useContentPage,
   useHead,
@@ -22,7 +27,7 @@ import { useGinkoOgImage } from "#ginko-docs/composables/useGinkoOgImage";
 import { useSchemaJsonLd } from "#ginko-docs/composables/useSchemaJsonLd";
 import DocumentPageShell from "#ginko-docs/components/content/DocumentPageShell.vue";
 import PageMarkdownCopy from "#ginko-docs/components/content/PageMarkdownCopy.vue";
-import { syncContentRouteAlternates } from "#ginko-docs/composables/useContentRouteAlternates";
+import { useContentRouteAlternates } from "#ginko-docs/composables/useContentRouteAlternates";
 
 definePageMeta({ layout: "blog" });
 
@@ -30,26 +35,26 @@ const { locale, t } = useI18n();
 const config = useAppConfig().ginkoDocs;
 const route = useRoute();
 const localizedPath = useLocalizedPath();
+const canonicalUrl = useCanonicalUrl();
+const { sync: syncContentRouteAlternates } = useContentRouteAlternates();
 const {
   page: post,
   previous,
   next,
   error,
 } = await useContentPage("blog", {
-  locale: () => locale.value,
   fallback: true,
   populate: { author: "authors" },
   surround: true,
 });
 if (error.value) throw error.value;
-if (!post.value) throw createContentNotFoundError();
+if (!post.value) throw createError({ statusCode: 404, statusMessage: "Not Found" });
 syncContentRouteAlternates(post);
 
 const pageTitle = computed(() => post.value?.title ?? t("blog.fallbackTitle"));
 const pageDescription = computed(() => post.value?.description ?? t("blog.fallbackDescription"));
-const canonicalUrl = useCanonicalUrl();
 const tocItems = computed(() =>
-  filterTocByDepth(flattenTocLinks(post.value?.body?.toc?.links), config.toc?.depth ?? 3),
+  filterTocByDepth(flattenTocLinks(getMarkdownTocLinks(post.value?.body)), config.toc?.depth ?? 3),
 );
 const formattedDate = computed(() => formatContentDate(post.value?.date, locale.value));
 const siteName = computed(() => getLocalizedSiteText(config.site.name, locale.value));
@@ -75,7 +80,16 @@ useGinkoOgImage({
 });
 
 useHead(() => ({
-  link: [{ key: "canonical", rel: "canonical", href: canonicalUrl.value }],
+  link: [
+    { key: "canonical", rel: "canonical", href: canonicalUrl.value },
+    {
+      key: "rss",
+      rel: "alternate",
+      type: "application/rss+xml",
+      title: `${t("blog.title")} - ${siteName.value}`,
+      href: `${localizedPath("blog")}/rss.xml`,
+    },
+  ],
   meta: [{ property: "og:type", content: "article" }],
 }));
 
@@ -181,7 +195,10 @@ useSchemaJsonLd(() =>
       <ContentRenderer :value="post" />
     </div>
 
-    <ContentFeedback :label="t('feedback.articleLabel')" />
+    <ContentFeedback
+      class="mt-14 border-y border-border py-5"
+      :label="t('feedback.articleLabel')"
+    />
 
     <div v-if="suggestions.length" class="mt-14">
       <h2 class="mb-6 text-sm font-semibold tracking-wider text-muted-foreground uppercase">

package/app/pages/blog/index.vue

@@ -6,24 +6,16 @@ import { getLocalizedSiteText } from "#ginko-docs/config/site.utils";
 import { computed } from "vue";
 import { definePageMeta, useAppConfig, useAsyncData, useHead, useI18n, useSeoMeta } from "#imports";
 import { useCanonicalUrl } from "#ginko-docs/composables/useCanonicalUrl";
+import { useLocalizedPath } from "#ginko-docs/composables/useLocalizedPath";
+
+const MAX_BLOG_POSTS = 50;
 
 definePageMeta({ layout: "blog" });
 
 const { locale, t } = useI18n();
 const postsKey = computed(() => `blog-posts:${locale.value}`);
-const { data: posts } = await useAsyncData(
-  postsKey,
-  () =>
-    many("blog", {
-      locale: locale.value,
-      fallback: true,
-      populate: { author: "authors" },
-      sort: { date: "desc" },
-      limit: 50,
-    }),
-  { watch: [locale] },
-);
 const canonicalUrl = useCanonicalUrl();
+const localizedPath = useLocalizedPath();
 const config = useAppConfig().ginkoDocs;
 const siteName = computed(() => getLocalizedSiteText(config.site.name, locale.value));
 const fullTitle = computed(() => `${t("blog.pageTitle")} - ${siteName.value}`);
@@ -38,8 +30,37 @@ useSeoMeta({
 });
 
 useHead(() => ({
-  link: [{ key: "canonical", rel: "canonical", href: canonicalUrl.value }],
+  link: [
+    { key: "canonical", rel: "canonical", href: canonicalUrl.value },
+    {
+      key: "rss",
+      rel: "alternate",
+      type: "application/rss+xml",
+      title: fullTitle.value,
+      href: `${localizedPath("blog")}/rss.xml`,
+    },
+  ],
 }));
+
+const { data: queriedPosts, error } = await useAsyncData(
+  postsKey,
+  () =>
+    many("blog", {
+      locale: locale.value,
+      fallback: true,
+      populate: { author: "authors" },
+      sort: { date: "desc" },
+      limit: MAX_BLOG_POSTS + 1,
+    }),
+  { watch: [locale] },
+);
+if (error.value) throw error.value;
+if ((queriedPosts.value?.length ?? 0) > MAX_BLOG_POSTS) {
+  throw new Error(
+    `Blog supports at most ${MAX_BLOG_POSTS} posts; add pagination before publishing more`,
+  );
+}
+const posts = computed(() => queriedPosts.value ?? []);
 </script>
 
 <template>
@@ -49,7 +70,10 @@ useHead(() => ({
       <p class="mt-2 text-muted-foreground">{{ t("blog.description") }}</p>
     </div>
 
-    <div class="divide-y divide-border">
+    <p v-if="posts.length === 0" class="py-12 text-center text-sm text-muted-foreground">
+      {{ t("blog.empty") }}
+    </p>
+    <div v-else class="divide-y divide-border">
       <article v-for="post in posts" :key="post.route.resolvedPath" class="group py-8">
         <NuxtLink
           :to="post.route.resolvedPath"

package/app/pages/docs/index.vue

@@ -1,23 +1,19 @@
 <script setup lang="ts">
-import { definePageMeta, navigateTo, useRoute } from "#imports";
-import { useDocsEntryPath } from "#ginko-docs/features/docs/composables/useDocsEntryPath";
+import { findFirstNavigationPage } from "@lupinum/ginko-content/navigation";
+import { createError, definePageMeta, navigateTo } from "#imports";
+import { useDocsNavigationData } from "#ginko-docs/features/docs/composables/useDocsNavigationData";
 
 definePageMeta({ layout: "docs" });
 
-const route = useRoute();
-const entryPath = await useDocsEntryPath();
-
-// Redirect the bare docs root to the first documentation page. Guard against
-// self-redirects when no docs pages exist (entry path falls back to the root).
-if (entryPath.value && entryPath.value !== route.path) {
-  await navigateTo(entryPath.value, { redirectCode: 302, replace: true });
+const { data, error } = await useDocsNavigationData();
+if (error.value) throw error.value;
+const entryPath = findFirstNavigationPage(data.value ?? undefined)?.path;
+if (!entryPath) {
+  throw createError({ statusCode: 404, statusMessage: "Documentation is empty" });
 }
+await navigateTo(entryPath, { redirectCode: 302, replace: true });
 </script>
 
 <template>
-  <main id="main-content" class="flex-1 px-4 py-12 md:px-6">
-    <NuxtLink v-if="entryPath && entryPath !== route.path" :to="entryPath" class="underline">
-      {{ entryPath }}
-    </NuxtLink>
-  </main>
+  <main id="main-content" />
 </template>