Add preface to website table of contents

- Add FrontMatterItem type for standalone front matter items
- Update build-book-structure to include preface in BookData
- Add preface link to book-nav component before parts
- Create /book/preface page route
- Fix CI to use npm run build (triggers prebuild hook)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: testac974

website/.github/workflows/deploy-pages.yml

@@ -41,7 +41,7 @@ jobs:
         run: npm ci
 
       - name: Build
-        run: npx next build
+        run: npm run build
         env:
           NEXT_PUBLIC_BASE_PATH: ""
 

website/app/book/preface/page.tsx

@@ -0,0 +1,107 @@
+import { MermaidDiagram } from "@/components/mermaid-diagram"
+import { ChevronRight } from "lucide-react"
+import Link from "next/link"
+import { Button } from "@/components/ui/button"
+import { getFlatSections } from "@/lib/book-data-server"
+import { parseMarkdownFile, extractMermaidDiagrams } from "@/lib/markdown"
+import { notFound } from "next/navigation"
+import path from "path"
+
+export default async function PrefacePage() {
+  // Get the flat section list for navigation to first chapter
+  const flat = getFlatSections()
+  const next = flat.length > 0 ? flat[0] : null
+
+  // Load and parse markdown
+  let markdownData
+  try {
+    const filePath = path.join(process.cwd(), '..', 'book', 'preface.md')
+    markdownData = await parseMarkdownFile(filePath)
+  } catch (error) {
+    console.error('Error loading preface:', error)
+    notFound()
+  }
+
+  const { frontmatter, content, htmlContent } = markdownData
+
+  // Extract mermaid diagrams
+  const mermaidDiagrams = extractMermaidDiagrams(content)
+
+  return (
+    <article className="py-12 px-6 lg:px-12 max-w-3xl">
+      {/* Breadcrumb */}
+      <div className="flex items-center gap-2 text-sm text-muted-foreground mb-8">
+        <Link href="/" className="hover:text-foreground transition-colors">
+          Home
+        </Link>
+        <span>/</span>
+        <span>Preface</span>
+      </div>
+
+      {/* Header */}
+      <header className="mb-12">
+        <h1 className="text-3xl sm:text-4xl font-bold tracking-tight mb-4 text-balance">
+          {frontmatter.title || 'Preface'}
+        </h1>
+        {frontmatter.abstract && (
+          <p className="text-lg text-muted-foreground">
+            {frontmatter.abstract}
+          </p>
+        )}
+      </header>
+
+      {/* Content */}
+      <div
+        className="prose prose-invert prose-green max-w-none"
+        dangerouslySetInnerHTML={{ __html: htmlContent }}
+      />
+
+      {/* Mermaid diagrams */}
+      {mermaidDiagrams.map((diagram, index) => (
+        <div key={index} className="my-8">
+          <MermaidDiagram
+            chart={diagram}
+            caption={`Figure ${index + 1}`}
+          />
+        </div>
+      ))}
+
+      {/* Navigation */}
+      <nav className="mt-16 pt-8 border-t border-border flex items-center justify-between">
+        <Button variant="ghost" disabled className="text-muted-foreground">
+          Previous
+        </Button>
+        {next ? (
+          <Button variant="ghost" asChild>
+            <Link href={next.href} className="flex items-center gap-2">
+              <span className="hidden sm:inline">Start Reading: {next.sectionTitle}</span>
+              <span className="sm:hidden">Next</span>
+              <ChevronRight className="h-4 w-4" />
+            </Link>
+          </Button>
+        ) : (
+          <Button variant="ghost" disabled className="text-muted-foreground">
+            Next
+            <ChevronRight className="h-4 w-4 ml-2" />
+          </Button>
+        )}
+      </nav>
+    </article>
+  )
+}
+
+export async function generateMetadata() {
+  try {
+    const filePath = path.join(process.cwd(), '..', 'book', 'preface.md')
+    const { frontmatter } = await parseMarkdownFile(filePath)
+
+    return {
+      title: `${frontmatter.title || 'Preface'} | Agentic Coding Playbook`,
+      description: frontmatter.abstract || 'Preface to the Agentic Coding Playbook',
+    }
+  } catch (error) {
+    return {
+      title: 'Preface | Agentic Coding Playbook',
+    }
+  }
+}

website/components/book-nav.tsx

@@ -5,7 +5,7 @@ import { usePathname } from "next/navigation"
 import { ChevronDown, ChevronRight } from "lucide-react"
 import { useState, useEffect } from "react"
 import { cn } from "@/lib/utils"
-import { bookStructure } from "@/lib/book-data"
+import { bookStructure, frontMatter } from "@/lib/book-data"
 
 export function BookNav({ onNavigate }: { onNavigate?: () => void }) {
   const pathname = usePathname()
@@ -58,6 +58,28 @@ export function BookNav({ onNavigate }: { onNavigate?: () => void }) {
         Table of Contents
       </p>
 
+      {/* Front matter (Preface, etc.) */}
+      {frontMatter.map((item) => {
+        const href = `/book/${item.slug}`
+        const isActive = pathname === href
+        return (
+          <Link
+            key={item.slug}
+            href={href}
+            onClick={onNavigate}
+            className={cn(
+              "block py-1.5 px-2 rounded-md transition-colors font-medium",
+              isActive
+                ? "bg-primary/10 text-primary"
+                : "text-foreground hover:bg-muted",
+            )}
+            aria-current={isActive ? "page" : undefined}
+          >
+            {item.title}
+          </Link>
+        )
+      })}
+
       {bookStructure.map((part, partIndex) => {
         const isPartAvailable = part.available
         return (

website/lib/book-data-server.ts

@@ -1,25 +1,28 @@
 import 'server-only'
 import { buildBookStructure, getFlatSections as getFlatSectionsFromParts } from './build-book-structure'
-import type { Part, Chapter, Section } from './book-types'
+import type { Part, Chapter, Section, BookData, FrontMatterItem } from './book-types'
 
 /**
  * Server-side function to get book structure
  * This uses fs and can only be called from server components
  */
-export function getBookStructure(): Part[] {
+export function getBookStructure(): BookData {
   try {
     return buildBookStructure()
   } catch (error) {
     console.error('Error building book structure:', error)
     // Fallback to minimal structure
-    return [
-      {
-        title: "Foundations",
-        slug: "foundations",
-        available: true,
-        chapters: [],
-      },
-    ]
+    return {
+      frontMatter: [],
+      parts: [
+        {
+          title: "Foundations",
+          slug: "foundations",
+          available: true,
+          chapters: [],
+        },
+      ],
+    }
   }
 }
 
@@ -37,7 +40,7 @@ export type FlatSection = {
 
 export function getFlatSections(): FlatSection[] {
   const structure = getBookStructure()
-  return getFlatSectionsFromParts(structure).map(section => ({
+  return getFlatSectionsFromParts(structure.parts).map(section => ({
     partTitle: section.partTitle,
     chapterTitle: section.chapterTitle,
     sectionTitle: section.sectionTitle,
@@ -46,3 +49,11 @@ export function getFlatSections(): FlatSection[] {
     filePath: section.filePath,
   }))
 }
+
+/**
+ * Server-side function to get front matter items
+ */
+export function getFrontMatter(): FrontMatterItem[] {
+  const structure = getBookStructure()
+  return structure.frontMatter
+}

website/lib/book-data.ts

@@ -1,13 +1,16 @@
 import bookStructureData from './book-structure.json'
-import type { Part, Section, Chapter, FlatSection } from './book-types'
+import type { Part, Section, Chapter, FlatSection, FrontMatterItem, BookData } from './book-types'
 
 /**
  * Book structure loaded from pre-generated JSON
  * This can be safely used in both client and server components
  */
-export const bookStructure: Part[] = bookStructureData as Part[]
+const data = bookStructureData as BookData
 
-export type { Part, Section, Chapter, FlatSection }
+export const bookStructure: Part[] = data.parts
+export const frontMatter: FrontMatterItem[] = data.frontMatter
+
+export type { Part, Section, Chapter, FlatSection, FrontMatterItem, BookData }
 
 /**
  * Build a flat list of all navigable sections with prev/next links