refactor(navigation): improve navigation building logic

HYP3R00T · HYP3R00T · commit e19ae072db3b · 2026-01-31T21:15:12.000+05:30
diff --git a/content/docs/content/markdown/working-with-images.mdx b/content/docs/content/markdown/working-with-images.mdx
@@ -204,7 +204,7 @@ git commit -m "Update setup guide and screenshot"
 
 For large images, consider Git LFS:
 
-```gitattributes
+```shell
 *.jpg filter=lfs diff=lfs merge=lfs -text
 *.png filter=lfs diff=lfs merge=lfs -text
 *.webp filter=lfs diff=lfs merge=lfs -text
diff --git a/src/components/core/HeaderMobileMenu.astro b/src/components/core/HeaderMobileMenu.astro
@@ -4,7 +4,7 @@ import { Button } from "@/components/ui/button";
 import { HEADER_SOCIAL_LINKS, HEADER_NAV_ITEMS, CONTENT, SIDEBAR_NAVIGATION } from "@data/config";
 import DocsTabs from "@/components/docs/DocsTabs.astro";
 import DocsContent from "@/components/docs/DocsContent.astro";
-import { buildNavigation, getActiveTab } from "@/lib/navigation";
+import { getActiveTab, buildNavigation } from "@/lib/navigation";
 
 const activeSocials = HEADER_SOCIAL_LINKS.filter((social) => social.active);
 const menuPanelId = "mobile-menu";
@@ -26,7 +26,12 @@ const currentSlug = baseRoute
     ? normalizedPath.slice(baseRoute.length).replace(/^\/+/, "") || null
     : null;
 
-const navResult = collectionId ? await buildNavigation(SIDEBAR_NAVIGATION, collectionId) : null;
+// Build navigation for the current collection
+let navResult = null;
+if (collectionId) {
+    navResult = await buildNavigation(SIDEBAR_NAVIGATION, collectionId);
+}
+
 const activeTab = navResult
     ? currentSlug
         ? getActiveTab(currentSlug, navResult.tabs)
diff --git a/src/integrations/prebuildNavigation.mjs b/src/integrations/prebuildNavigation.mjs
@@ -0,0 +1,50 @@
+import fs from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+
+/**
+ * Astro integration that prebuilds navigation for all collections at build time.
+ * Note: The actual prebuild happens in getStaticPaths() for each page.
+ * This integration creates a JSON export of the prebuilt navigation for reference.
+ */
+export function prebuildNavigationIntegration() {
+    let outDir = null;
+
+    return {
+        name: "prebuild-navigation",
+        hooks: {
+            "astro:config:done": ({ config }) => {
+                outDir = config.outDir;
+            },
+            "astro:build:done": async () => {
+                try {
+                    console.log(
+                        "[prebuild-navigation] Build completed - navigation was prebuilt during page generation",
+                    );
+                    console.log(`[prebuild-navigation] ✓ Output directory: ${outDir}`);
+
+                    // Verify nav JSON files exist
+                    if (outDir) {
+                        const navDir = path.join(fileURLToPath(outDir), "nav");
+                        try {
+                            const files = await fs.readdir(navDir);
+                            const jsonFiles = files.filter((f) => f.endsWith(".json"));
+                            console.log(
+                                `[prebuild-navigation] ✓ Generated ${jsonFiles.length} navigation file(s): ${jsonFiles.join(", ")}`,
+                            );
+                        } catch (readErr) {
+                            console.warn(
+                                "[prebuild-navigation] Note: Nav directory not created (may be normal for dev builds)",
+                            );
+                        }
+                    }
+                } catch (error) {
+                    console.error(
+                        "[prebuild-navigation] Error in build:done hook:",
+                        error instanceof Error ? error.message : String(error),
+                    );
+                }
+            },
+        },
+    };
+}
diff --git a/src/layouts/DocsLayout.astro b/src/layouts/DocsLayout.astro
@@ -5,16 +5,25 @@ import TableOfContents from "@/components/docs/TableOfContents.astro";
 import Breadcrumb from "@/components/docs/Breadcrumb.astro";
 import SourceButton from "@/components/docs/SourceButton.astro";
 import CodeCopyButton from "@/components/docs/CodeCopyButton.astro";
-import { buildNavigation, getActiveTab } from "@/lib/navigation";
+import { getActiveTab } from "@/lib/navigation";
 import { buildBreadcrumbItems } from "@/lib/docs/breadcrumb";
-import { SIDEBAR_NAVIGATION } from "@data/config";
 import type { DocsLayoutProps, Heading } from "@/lib/docs/types";
+import type { NavigationResult } from "@/lib/navigation/types";
 
-const props = Astro.props as DocsLayoutProps;
-const { headings = [], frontmatter, collection } = props;
+interface Props extends DocsLayoutProps {
+    nav?: NavigationResult;
+}
+
+const props = Astro.props as Props;
+const { headings = [], frontmatter, collection, nav } = props;
 const collectionId = collection ?? "docs";
-const navResult = await buildNavigation(SIDEBAR_NAVIGATION, collectionId);
-const activeTab = getActiveTab(frontmatter.id, navResult.tabs);
+
+// Use prebuilt nav or handle missing nav gracefully
+if (!nav) {
+    throw new Error(`Navigation data missing for collection: ${collectionId}`);
+}
+
+const activeTab = getActiveTab(frontmatter.id, nav.tabs);
 
 // Build breadcrumb items
 const breadcrumbItems = buildBreadcrumbItems(frontmatter.id, collectionId);
@@ -33,8 +42,8 @@ const tableOfContentsHeadings = headings
     <div class="flex min-h-screen">
         <!-- Sidebar with tabs inside  -->
         <Sidebar
-            tabs={navResult.tabs}
-            showTabs={navResult.showTabs}
+            tabs={nav.tabs}
+            showTabs={nav.showTabs}
             activeTab={activeTab}
             currentSlug={frontmatter.id}
             collectionId={collectionId}
diff --git a/src/pages/[collection]/[...slug].astro b/src/pages/[collection]/[...slug].astro
@@ -4,33 +4,38 @@ import type { CollectionKey } from "astro:content";
 import DocsLayout from "@/layouts/DocsLayout.astro";
 import MdxImage from "@/components/docs/markdown/MdxImage.astro";
 import MdxLink from "@/components/docs/markdown/MdxLink.astro";
-import { CONTENT } from "@data/config";
+import { CONTENT, SIDEBAR_NAVIGATION } from "@data/config";
+import { buildNavigation } from "@/lib/navigation";
 
 export async function getStaticPaths() {
     const paths: {
         params: { collection: CollectionKey; slug: string };
         props: {
             doc: Awaited<ReturnType<typeof getCollection>>[number];
             collection: CollectionKey;
+            nav: Awaited<ReturnType<typeof buildNavigation>>;
         };
     }[] = [];
 
     for (const sys of CONTENT.systems) {
+        const nav = await buildNavigation(SIDEBAR_NAVIGATION, sys.id);
+
         const entries = await getCollection(sys.id as CollectionKey);
         for (const doc of entries) {
             paths.push({
                 params: { collection: sys.id as CollectionKey, slug: doc.id },
-                props: { doc, collection: sys.id as CollectionKey },
+                props: { doc, collection: sys.id as CollectionKey, nav },
             });
         }
     }
 
     return paths;
 }
 
-const { doc, collection } = Astro.props as {
+const { doc, collection, nav } = Astro.props as {
     doc: Awaited<ReturnType<typeof getCollection>>[number];
     collection: CollectionKey;
+    nav: Awaited<ReturnType<typeof buildNavigation>>;
 };
 const { Content, headings } = await render(doc);
 
@@ -40,6 +45,6 @@ const components = {
 };
 ---
 
-<DocsLayout frontmatter={doc} headings={headings} collection={collection}>
+<DocsLayout frontmatter={doc} headings={headings} collection={collection} nav={nav}>
     <Content components={components} />
 </DocsLayout>
diff --git a/src/pages/[collection]/index.astro b/src/pages/[collection]/index.astro
@@ -1,33 +1,65 @@
 ---
 import { getCollection, render } from "astro:content";
 import type { CollectionKey } from "astro:content";
-import { CONTENT } from "@data/config";
+import { CONTENT, SIDEBAR_NAVIGATION } from "@data/config";
 import DocsLayout from "@/layouts/DocsLayout.astro";
 import MdxImage from "@/components/docs/markdown/MdxImage.astro";
 import MdxLink from "@/components/docs/markdown/MdxLink.astro";
+import { buildNavigation } from "@/lib/navigation";
 
 export async function getStaticPaths() {
-    const paths: { params: { collection: CollectionKey }; props: { collection: CollectionKey } }[] =
-        [];
+    const paths: {
+        params: { collection: CollectionKey };
+        props: {
+            collection: CollectionKey;
+            nav: Awaited<ReturnType<typeof buildNavigation>>;
+            doc: Awaited<ReturnType<typeof getCollection>>[number] | undefined;
+        };
+    }[] = [];
+
     for (const sys of CONTENT.systems) {
+        const nav = await buildNavigation(SIDEBAR_NAVIGATION, sys.id);
+        const entries = await getCollection(sys.id as CollectionKey);
+
+        // Check if index doc exists, if not use the default redirect target
+        let indexDoc = entries.find((entry) => entry.id === "index");
+
+        if (!indexDoc) {
+            // Find the default doc to render instead
+            const defaultRedirect = sys.defaultDocRedirect;
+            if (defaultRedirect) {
+                // Extract slug from redirect path (e.g., "/docs/introduction" -> "introduction")
+                const baseRoute = sys.route ?? `/${sys.id}`;
+                const defaultSlug = defaultRedirect
+                    .replace(baseRoute + "/", "")
+                    .replace(/^\/+/, "");
+                indexDoc = entries.find((entry) => entry.id === defaultSlug);
+            }
+        }
+
         paths.push({
             params: { collection: sys.id as CollectionKey },
-            props: { collection: sys.id as CollectionKey },
+            props: {
+                collection: sys.id as CollectionKey,
+                nav,
+                doc: indexDoc,
+            },
         });
     }
+
     return paths;
 }
 
 const collection = Astro.params.collection as CollectionKey;
-
-const entries = await getCollection(collection);
-const doc = entries.find((entry) => entry.id === "index");
+const { nav, doc } = Astro.props as {
+    collection: CollectionKey;
+    nav: Awaited<ReturnType<typeof buildNavigation>>;
+    doc: Awaited<ReturnType<typeof getCollection>>[number] | undefined;
+};
 
 if (!doc) {
-    return Astro.redirect(
-        (CONTENT.systems ?? []).find((system) => system.id === collection)?.defaultDocRedirect ??
-            "/",
-    );
+    // Fallback to home if no doc found at all
+    return Astro.redirect("/");
 }
 
 const { Content, headings } = await render(doc);
@@ -38,6 +70,6 @@ const components = {
 };
 ---
 
-<DocsLayout frontmatter={doc} headings={headings} collection={collection}>
+<DocsLayout frontmatter={doc} headings={headings} collection={collection} nav={nav}>
     <Content components={components} />
 </DocsLayout>
diff --git a/src/pages/debug/navigation.json.ts b/src/pages/debug/navigation.json.ts
@@ -1,11 +1,18 @@
 import type { APIRoute } from "astro";
 import { buildNavigation } from "@/lib/navigation";
-import { SIDEBAR_NAVIGATION } from "@data/config";
+import { SIDEBAR_NAVIGATION, CONTENT } from "@data/config";
 
 export const GET: APIRoute = async () => {
     try {
-        const nav = await buildNavigation(SIDEBAR_NAVIGATION);
-        return new Response(JSON.stringify(nav, null, 2), {
+        const allNav: Record<string, unknown> = {};
+
+        // Build navigation for all collections
+        for (const system of CONTENT.systems) {
+            const nav = await buildNavigation(SIDEBAR_NAVIGATION, system.id);
+            allNav[system.id] = nav;
+        }
+
+        return new Response(JSON.stringify(allNav, null, 2), {
             headers: {
                 "Content-Type": "application/json; charset=utf-8",
             },
