This document describes the architecture of the Zod documentation website located in packages/docs/. It covers the Next.js-based site structure, content management through MDX files, the fumadocs-ui integration, dynamic routing, ecosystem integration with GitHub's GraphQL API, and deployment configuration. For information about the Zod library build and release process, see Build System and CI/CD. For details on contributing to documentation content, see Contributing Guidelines.
The documentation site is a Next.js 14+ application using the App Router, with static site generation (SSG) for all documentation pages. It leverages fumadocs-ui for the documentation layout and UI components, and fumadocs-mdx for MDX content processing.
Sources: packages/docs/app/(doc)/[[...slug]]/page.tsx:1-117, packages/docs/app/(doc)/layout.tsx1-75 packages/docs/app/layout.tsx1-54 packages/docs/loaders/stars.ts1-81
Documentation content is authored in MDX files located in packages/docs/content/. The fumadocs-mdx library processes these files and generates a page tree structure through the source object.
The page.data.body component is rendered with custom MDX components including:
Heading (h1-h6) with anchor linksCallout (blockquote styling)Tabs for code examplescreateRelativeLink for internal page navigationSources: packages/docs/app/(doc)/[[...slug]]/page.tsx:19-30, packages/docs/app/(doc)/[[...slug]]/page.tsx:54-69
The documentation site uses Next.js's catch-all route pattern [[...slug]] to handle all documentation pages dynamically while generating them statically at build time.
| Route Pattern | Example URL | Rendered Page |
|---|---|---|
/ | https://zod.dev/ | Index/intro page |
/[slug] | https://zod.dev/basics | Single-level page |
/[...slug] | https://zod.dev/api/primitives | Nested pages |
The site sets revalidate = 86400 (24 hours) and dynamic = "force-static" to ensure all pages are pre-rendered and cached.
Sources: packages/docs/app/(doc)/[[...slug]]/page.tsx:12-13, packages/docs/app/(doc)/[[...slug]]/page.tsx:75-77
The documentation site has a nested layout structure with version switching capabilities.
The sidebar includes a tab switcher between Zod 4 and Zod 3 documentation:
The SidebarLogo component handles image preloading and fade-in transitions to prevent FOUC (Flash of Unstyled Content).
Sources: packages/docs/app/(doc)/layout.tsx11-74 packages/docs/app/layout.tsx16-53 packages/docs/components/sidebar-logo.tsx1-24
The documentation site displays third-party libraries in the ecosystem with live GitHub star counts, sorted by popularity.
The fetchStars function:
{ repo0: repository(...) { stargazerCount } repo1: ... }GITHUB_TOKENnext: { revalidate: 86400 }Sources: packages/docs/components/ecosystem.tsx1-391 packages/docs/loaders/stars.ts1-81
| Component | Purpose | Location |
|---|---|---|
CopyMarkdownButton | Copy page markdown content | packages/docs/components/copy-markdown-button.tsx1-38 |
Heading | Heading with anchor links | Referenced in packages/docs/app/(doc)/[[...slug]]/page.tsx:62-67 |
Tabs | Code example switcher | Referenced in packages/docs/app/(doc)/[[...slug]]/page.tsx:61 |
SidebarLogo | Logo with fade-in loading | packages/docs/components/sidebar-logo.tsx1-24 |
HeroLogo | Homepage hero logo | packages/docs/components/hero-logo.tsx1-45 |
SidebarItem | Custom sidebar item styling | Referenced in packages/docs/app/(doc)/layout.tsx20 |
SidebarSeparator | Custom separator styling | Referenced in packages/docs/app/(doc)/layout.tsx21 |
The CopyMarkdownButton component appears on every documentation page, allowing users to copy the raw markdown content:
The button displays a checkmark icon for 2 seconds after successful copying.
Sources: packages/docs/app/(doc)/[[...slug]]/page.tsx:23, packages/docs/app/(doc)/[[...slug]]/page.tsx:39, packages/docs/components/copy-markdown-button.tsx14-22
The site includes an extensive redirect system to maintain SEO and preserve old documentation URLs.
The next.config.mjs file defines a generateRedirects helper function that maps old query-parameter-based URLs to new path-based URLs:
| Category | Example Redirect | Destination |
|---|---|---|
| Intro pages | /?id=installation | / |
| Ecosystem | /?id=api-libraries | /ecosystem |
| Basic usage | /?id=parse | /basics |
| API reference | /?id=primitives | /api |
| Error handling | /ERROR_HANDLING?id=error-map-priority | /error-customization |
| Changelog | /CHANGELOG | https://github.com/colinhacks/zod/releases |
The system generates 200+ redirect rules to ensure backward compatibility with the previous documentation structure.
Sources: packages/docs/next.config.mjs11-35 packages/docs/next.config.mjs39-266
The site uses Inkeep for AI-powered search functionality, integrated through the fumadocs-ui provider system.
The search is accessible via keyboard shortcuts and appears in the navigation bar.
Sources: packages/docs/app/layout.tsx38-43 packages/docs/app/layout.tsx36
Each page generates dynamic metadata for SEO and social sharing.
The OpenGraph images are dynamically generated with the page title, description, and path encoded in query parameters.
Sources: packages/docs/app/(doc)/[[...slug]]/page.tsx:79-116
The documentation site enforces static generation with the following configuration:
This ensures:
The root layout preloads critical images to prevent FOUC:
Sources: packages/docs/app/(doc)/[[...slug]]/page.tsx:12-13, packages/docs/app/layout.tsx20-27
The site includes:
Sources: packages/docs/app/layout.tsx30-36 packages/docs/app/layout.tsx47-49
Refresh this wiki