feat(docs): split cookbooks per product and add how-to shelves

astro.config.mjs

@@ -120,7 +120,20 @@ export default defineConfig({
         ...(!process.env.NETLIFY
           ? [
               starlightLinksValidator({
-                exclude: ['/apis/**'],
+                // Blog listing, tag, and author pages are injected routes rather
+                // than content entries, so the validator cannot resolve them.
+                // Individual posts are real entries and stay validated.
+                exclude: [
+                  '/apis/**',
+                  '/agentkit/cookbooks/',
+                  '/saaskit/cookbooks/',
+                  '/agentkit/how-to/',
+                  '/saaskit/how-to/',
+                  '/agentkit/cookbooks/tags/**',
+                  '/saaskit/cookbooks/tags/**',
+                  '/agentkit/how-to/tags/**',
+                  '/saaskit/how-to/tags/**',
+                ],
               }),
             ]
           : []),
@@ -140,14 +153,50 @@ export default defineConfig({
           },
           // No baseUrl — prevents llms.txt generation (already handled by starlight-llms-txt)
         }),
-        starlightBlog({
-          prefix: 'cookbooks',
-          rss: false,
-          metrics: {
-            readingTime: true,
-            words: 'total',
+        // Array form: starlight-blog 0.28+ supports multiple blog instances, one
+        // per prefix. Posts map to an instance by directory (src/content/docs/<prefix>/).
+        // `navigation: 'none'` keeps each instance out of the header — with several
+        // instances the default ('header-end') stacks a link per blog beside the
+        // theme switcher. Discovery goes through the secondary nav instead.
+        starlightBlog([
+          {
+            prefix: 'agentkit/cookbooks',
+            title: 'AgentKit cookbooks',
+            navigation: 'none',
+            rss: false,
+            metrics: {
+              readingTime: true,
+              words: 'total',
+            },
           },
-        }),
+          {
+            prefix: 'saaskit/cookbooks',
+            title: 'Auth for SaaS cookbooks',
+            navigation: 'none',
+            rss: false,
+            metrics: {
+              readingTime: true,
+              words: 'total',
+            },
+          },
+          // How-to shelves carry short dashboard and workspace answers. Reading
+          // time is blog furniture that reads wrong on a two-minute "delete my
+          // account" answer, so it stays off here.
+          {
+            prefix: 'agentkit/how-to',
+            title: 'AgentKit how-to guides',
+            navigation: 'none',
+            rss: false,
+            metrics: { readingTime: false, words: false },
+          },
+          {
+            prefix: 'saaskit/how-to',
+            title: 'Auth for SaaS how-to guides',
+            navigation: 'none',
+            rss: false,
+            metrics: { readingTime: false, words: false },
+          },
+        ]),
       ],
       head: [
         {

package.json

@@ -53,7 +53,7 @@
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
     "sharp": "^0.35.3",
-    "starlight-blog": "^0.26.1",
+    "starlight-blog": "^0.28.0",
     "starlight-image-zoom": "^0.14.2",
     "starlight-links-validator": "^0.24.1",
     "starlight-llms-txt": "^0.10.0",

src/components/overrides/HeaderProductToggle.astro

@@ -220,15 +220,21 @@ const productLinks = [
         item.setAttribute('aria-selected', String(active))
       })
 
-    // Secondary nav dual-row: show the matching product's tab set on shared paths
-    document.querySelectorAll('.secondary-nav-product[data-product]').forEach((row) => {
-      const rowProduct = row.getAttribute('data-product')
-      if (rowProduct === product) {
-        row.removeAttribute('hidden')
-      } else {
-        row.setAttribute('hidden', '')
-      }
-    })
+    // Secondary nav dual-row: show the matching product's tab set on shared paths.
+    // Only shared paths render both rows. Everywhere else renders a single row for
+    // the current product, and hiding it would leave the nav empty until the next
+    // page finishes loading — so leave it alone and let navigation replace it.
+    const navRows = document.querySelectorAll('.secondary-nav-product[data-product]')
+    if (navRows.length > 1) {
+      navRows.forEach((row) => {
+        const rowProduct = row.getAttribute('data-product')
+        if (rowProduct === product) {
+          row.removeAttribute('hidden')
+        } else {
+          row.setAttribute('hidden', '')
+        }
+      })
+    }
 
     document.dispatchEvent(new CustomEvent('sk:product-context', { detail: { product } }))
   }

src/components/overrides/MarkdownContent.astro

@@ -1,10 +1,14 @@
 ---
-import Default from '@astrojs/starlight/components/MarkdownContent.astro'
+// starlight-blog's own override branches internally: blog posts get post chrome
+// (author byline, reading time), every other page falls through to Starlight's
+// default. Nesting it here keeps that behaviour — rendering Starlight's default
+// directly would shadow the plugin and silently drop the chrome.
+import BlogMarkdownContent from 'starlight-blog/overrides/MarkdownContent.astro'
 import VideosMarkdownContent from 'starlight-videos/components/MarkdownContent.astro'
 import ImageZoom from 'starlight-image-zoom/components/ImageZoom.astro'
 ---
 
 <ImageZoom />
 <VideosMarkdownContent>
-  <Default><slot /></Default>
+  <BlogMarkdownContent><slot /></BlogMarkdownContent>
 </VideosMarkdownContent>

src/configs/llms.config.ts

@@ -63,7 +63,7 @@ Start with the Quickstart Collection, then follow the developer's question to th
       label: 'AgentKit',
       description:
         'Complete AgentKit documentation with connectors, frameworks, and tool calling for AI agents',
-      paths: ['agentkit/**', 'dev-kit/ai-assisted-development/**', 'cookbooks/**'],
+      paths: ['agentkit/**', 'dev-kit/ai-assisted-development/**'],
     },
     {
       label: 'AgentKit Frameworks',
@@ -139,7 +139,8 @@ Start with the Quickstart Collection, then follow the developer's question to th
     '**/overview', // All overview pages
     '**/quickstart', // All quickstart guides
     'agentkit/examples/**', // Framework examples (high value for agent queries)
-    'cookbooks/**', // Practical cookbooks
+    'agentkit/cookbooks/**', // Practical AgentKit cookbooks
+    'saaskit/cookbooks/**', // Practical Auth for SaaS cookbooks
     'fsa/data-modelling', // Critical data modeling guide
     'authenticate/set-up-scalekit', // Initial setup
     'authenticate/fsa/complete-login', // Core FSA flow