fix: sanitize docs navigation and add section redirects

Prevent prerender from following dead docs links by stripping non-page navigation paths, filtering surround links, and redirecting legacy section URLs to valid docs pages.

Made-with: Cursor

Author: OskarLebuda

app/app.vue

@@ -1,8 +1,17 @@
 <script setup lang="ts">
+import { stripFolderOnlyNavPaths } from '~/utils/sanitize-docs-navigation';
+
 const { seo } = useAppConfig();
 const site = useSiteConfig();
 
 const { data: navigation } = await useAsyncData('navigation', () => queryCollectionNavigation('docs'));
+const { data: docsPathRows } = await useAsyncData('docs-path-index', () => queryCollection('docs').select('path').all());
+
+const docsPathSet = computed(
+  () => new Set((docsPathRows.value ?? []).map((row) => row.path).filter(Boolean) as string[]),
+);
+
+const navigationDisplay = computed(() => stripFolderOnlyNavPaths(navigation.value ?? [], docsPathSet.value));
 const { data: files } = useLazyAsyncData('search', () => queryCollectionSearchSections('docs'), {
   server: false,
 });
@@ -128,6 +137,7 @@ useHead({
 });
 
 provide('navigation', navigation);
+provide('navigationDisplay', navigationDisplay);
 </script>
 
 <template>
@@ -143,7 +153,7 @@ provide('navigation', navigation);
     <AppFooter />
 
     <ClientOnly>
-      <LazyUContentSearch :files="files" :navigation="navigation" />
+      <LazyUContentSearch :files="files" :navigation="navigationDisplay" />
     </ClientOnly>
   </UApp>
 </template>

app/components/AppHeader.vue

@@ -33,15 +33,20 @@
     </template>
 
     <template #body>
-      <UContentNavigation highlight :navigation="navigation" />
+      <UContentNavigation highlight :navigation="mobileNavigation" />
     </template>
   </UHeader>
 </template>
 
 <script setup lang="ts">
 import type { ContentNavigationItem } from '@nuxt/content';
 
-const navigation = inject<Ref<ContentNavigationItem[]>>('navigation');
+const navigation = inject<Ref<ContentNavigationItem[]>>('navigation', ref([]));
+const navigationDisplay = inject<ComputedRef<ContentNavigationItem[]>>('navigationDisplay');
+
+const mobileNavigation = computed(
+  () => navigationDisplay?.value ?? navigation.value,
+);
 
 const { header } = useAppConfig();
 </script>

app/components/AppSurround.vue

@@ -5,8 +5,8 @@ const props = defineProps<{
   surround: ContentNavigationItem[];
 }>();
 
-const prev = computed(() => props.surround[0]);
-const next = computed(() => props.surround[1]);
+const prev = computed(() => (props.surround[0]?.path ? props.surround[0] : null));
+const next = computed(() => (props.surround[1]?.path ? props.surround[1] : null));
 </script>
 
 <template>

app/error.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import type { NuxtError } from '#app';
+import { stripFolderOnlyNavPaths } from '~/utils/sanitize-docs-navigation';
 
 defineProps<{
   error: NuxtError;
@@ -17,11 +18,20 @@ useSeoMeta({
 });
 
 const { data: navigation } = await useAsyncData('navigation', () => queryCollectionNavigation('docs'));
+const { data: docsPathRows } = await useAsyncData('docs-path-index', () => queryCollection('docs').select('path').all());
+
+const docsPathSet = computed(
+  () => new Set((docsPathRows.value ?? []).map((row) => row.path).filter(Boolean) as string[]),
+);
+
+const navigationDisplay = computed(() => stripFolderOnlyNavPaths(navigation.value ?? [], docsPathSet.value));
+
 const { data: files } = useLazyAsyncData('search', () => queryCollectionSearchSections('docs'), {
   server: false,
 });
 
 provide('navigation', navigation);
+provide('navigationDisplay', navigationDisplay);
 </script>
 
 <template>
@@ -33,7 +43,7 @@ provide('navigation', navigation);
     <AppFooter />
 
     <ClientOnly>
-      <LazyUContentSearch :files="files" :navigation="navigation" />
+      <LazyUContentSearch :files="files" :navigation="navigationDisplay" />
     </ClientOnly>
   </UApp>
 </template>

app/layouts/docs.vue

@@ -1,8 +1,13 @@
 <script setup lang="ts">
 import type { ContentNavigationItem } from '@nuxt/content';
 
-const navigation = inject<Ref<ContentNavigationItem[]>>('navigation', ref([]));
-const docsNavigation = computed(() => navigation.value.find((item) => item.path === '/docs')?.children || []);
+const navigationDisplay = inject<ComputedRef<ContentNavigationItem[]>>(
+  'navigationDisplay',
+  computed(() => []),
+);
+const docsNavigation = computed(
+  () => navigationDisplay.value.find((item) => item.path === '/docs')?.children || [],
+);
 </script>
 
 <template>

app/pages/docs/[...slug].vue

@@ -17,6 +17,11 @@ const navigation = inject<Ref<ContentNavigationItem[]>>('navigation', ref([]));
 
 const route = useRoute();
 
+const { data: docsPathRows } = await useAsyncData('docs-path-index', () => queryCollection('docs').select('path').all());
+const docsPathSet = computed(
+  () => new Set((docsPathRows.value ?? []).map((row) => row.path).filter(Boolean) as string[]),
+);
+
 const { data: page } = await useAsyncData(kebabCase(route.path), () => queryCollection('docs').path(route.path).first());
 if (!page.value) {
   throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true });
@@ -28,10 +33,14 @@ const { data: surround } = await useAsyncData(`${kebabCase(route.path)}-surround
   });
 });
 
+const surroundDisplay = computed(() =>
+  (surround.value ?? []).filter((item) => item?.path && docsPathSet.value.has(item.path)),
+);
+
 const breadcrumb: ComputedRef<BreadcrumbLink[]> = computed(() =>
   mapContentNavigation(findPageBreadcrumb(navigation.value, page.value?.path)).map((link) => ({
     label: link.label,
-    to: link.to,
+    to: link.to && docsPathSet.value.has(link.to) ? link.to : undefined,
   })),
 );
 
@@ -97,7 +106,8 @@ const communityLinks = computed(() => [
   {
     icon: 'i-heroicons-lifebuoy-solid',
     label: 'Contributing',
-    to: '/docs/contributing',
+    to: 'https://github.com/vercube/vercube/blob/main/CONTRIBUTING.md',
+    target: '_blank',
   },
 ]);
 </script>
@@ -134,7 +144,7 @@ const communityLinks = computed(() => [
             </UButton>
           </div>
         </AppDivider>
-        <AppSurround :surround="surround as any" />
+        <AppSurround :surround="surroundDisplay as any" />
       </div>
     </UPageBody>
 

app/utils/sanitize-docs-navigation.ts

@@ -0,0 +1,26 @@
+import type { ContentNavigationItem } from '@nuxt/content';
+
+/**
+ * Drop `path` on nav nodes that don't map to a real markdown page.
+ * Keeps the section tree intact while preventing crawlers/users from following dead `/docs/...` links.
+ */
+export function stripFolderOnlyNavPaths(
+  items: ContentNavigationItem[],
+  pathsWithPage: Set<string>,
+): ContentNavigationItem[] {
+  return items.map((item) => {
+    const children = item.children?.length
+      ? stripFolderOnlyNavPaths(item.children, pathsWithPage)
+      : item.children;
+
+    const path = item.path;
+    const pathIsPage = path ? pathsWithPage.has(path) : false;
+
+    if (path && !pathIsPage) {
+      const { path: _drop, ...rest } = item;
+      return { ...rest, children } as ContentNavigationItem;
+    }
+
+    return { ...item, children } as ContentNavigationItem;
+  });
+}

nuxt.config.ts

@@ -50,6 +50,18 @@ export default defineNuxtConfig({
   routeRules: {
     '/': { prerender: true },
     '/docs': { redirect: { statusCode: 301, to: '/docs/getting-started' } },
+    '/docs/contributing': {
+      redirect: { statusCode: 301, to: 'https://github.com/vercube/vercube/blob/main/CONTRIBUTING.md' },
+    },
+    '/docs/core-features': { redirect: { statusCode: 301, to: '/docs/core-features/configuration' } },
+    '/docs/modules': { redirect: { statusCode: 301, to: '/docs/modules/mcp' } },
+    '/docs/advanced': { redirect: { statusCode: 301, to: '/docs/advanced/custom-decorator' } },
+    '/docs/modules/web-sockets': { redirect: { statusCode: 301, to: '/docs/modules/web-sockets/overview' } },
+    '/docs/modules/auth': { redirect: { statusCode: 301, to: '/docs/modules/auth/overview' } },
+    '/docs/modules/storage': { redirect: { statusCode: 301, to: '/docs/modules/storage/overview' } },
+    '/docs/modules/logger': { redirect: { statusCode: 301, to: '/docs/modules/logger/overview' } },
+    '/docs/modules/serverless': { redirect: { statusCode: 301, to: '/docs/modules/serverless/overview' } },
+    '/docs/core/validation': { redirect: { statusCode: 301, to: '/docs/core-features/validation' } },
     // Static hosting (GitHub Pages): docs must be prerendered so crawlers and OG validators get real
     // HTML with meta tags. Client-only shells look “empty” to bots.
     '/docs/**': { prerender: true },