文档网站

相关源文件

• apps/www/app/(app)/docs/[[...slug]]/page.tsx
• apps/www/app/(app)/examples/layout.tsx/examples/layout.tsx)
• apps/www/app/(app)/page.tsx/page.tsx)
• apps/www/components/announcement.tsx
• apps/www/components/docs-nav.tsx
• apps/www/components/icons.tsx
• apps/www/components/mobile-nav.tsx
• apps/www/components/page-header.tsx
• apps/www/components/site-header.tsx
• apps/www/content/docs/index.mdx
• apps/www/styles/globals.css

本文件详细介绍了 apps/www 文档网站的结构和功能。该网站是 shadcn/ui 组件库面向用户的主要网站，提供组件文档、安装指南、示例和交互式组件预览。

有关 MDX 处理和组件预览生成的信息，请参阅 MDX 处理。有关导航配置和文档组织结构的详细信息，请参阅 导航结构。

网站架构概述

该文档网站使用 Next.js 14 和 App Router 构建，并遵循结构化的布局模式，以确保所有页面具有一致的用户体验。

来源：apps/www/app/(app)/page.tsx44-99 apps/www/app/(app)/docs/[[...slug]]/page.tsx:84-154, apps/www/components/site-header.tsx11-45 apps/www/app/(app)/examples/layout.tsx41-81

页面路由与结构

该网站使用 Next.js App Router，为文档页面提供动态路由，并采用结构化的布局层级。

路由模式	文件位置	目的
/	app/(app)/page.tsx	落地页，包含主视觉区和组件预览
/docs/[...slug]	app/(app)/docs/[[...slug]]/page.tsx	动态文档页面
/examples	app/(app)/examples/layout.tsx	示例展示，带导航
/blocks	-	组件块画廊

动态文档路由系统使用 generateStaticParams 函数在构建时预生成所有文档页面。

来源：apps/www/app/(app)/docs/[[...slug]]/page.tsx:24-33, apps/www/app/(app)/docs/[[...slug]]/page.tsx:76-82

导航系统

该网站实施了多层导航系统，该系统可适应不同的屏幕尺寸并提供全面的网站导航。

页眉导航

SiteHeader 组件提供了主导航栏，具有响应式行为。

• 桌面端：MainNav 组件，提供完整的导航菜单。
• 移动端：MobileNav 组件，采用抽屉式导航。
• 全局操作：命令菜单、GitHub 链接和主题切换器。

来源：apps/www/components/site-header.tsx11-45 apps/www/components/mobile-nav.tsx17-104

文档导航

文档页面使用 DocsNav 组件进行侧边栏导航，该组件根据 docsConfig.sidebarNav 配置渲染导航项。

• 层级结构：带有嵌套导航项的章节标题。
• 活动状态：通过 pathname 匹配来高亮当前页面。
• 标签支持：显示新功能或 Beta 功能的徽章。
• 外部链接：处理外部链接，并带有正确的属性。

来源：apps/www/components/docs-nav.tsx10-86 apps/www/components/mobile-nav.tsx59-100

内容渲染系统

文档内容通过一个复杂的渲染管道进行处理，该管道将 MDX 处理与组件预览和目录生成相结合。

来源：apps/www/app/(app)/docs/[[...slug]]/page.tsx:84-154, apps/www/app/(app)/docs/[[...slug]]/page.tsx:35-74, apps/www/lib/toc.ts

样式和主题

该网站使用基于 CSS 自定义属性和 Tailwind CSS 工具的综合性 CSS-in-JS 主题系统。

CSS 变量系统

全局样式表定义了 CSS 自定义属性，以实现浅色和深色模式之间的一致主题。

变量类别	属性	目的
核心颜色	--background、--foreground、--primary	基础配色方案
组件颜色	--card、--popover、--secondary、--accent	UI 组件样式
状态颜色	--destructive、--muted、--border	交互状态
图表颜色	--chart-1 至 --chart-5	数据可视化
侧边栏颜色	--sidebar-background、--sidebar-foreground	导航样式

深色模式的实现使用 .dark 类选择器，用相应的深色主题值覆盖这些变量。

来源：apps/www/styles/globals.css5-76

布局工具类

该网站定义了自定义的工具类，以实现一致的布局和间距。

• 容器系统：container-wrapper 和 container 类，用于响应式宽度约束。
• 网格边框：border-grid 类，用于虚线边框样式。
• 步骤指示器：.step 工具类，用于编号的文档步骤。
• 滚动条样式：自定义 Webkit 滚动条外观。

来源：apps/www/styles/globals.css115-156

主要功能

组件预览系统

主页使用 CardsDemo 组件展示了交互式组件预览，该组件展示了具有响应式行为和主题支持的实时组件示例。

搜索和命令面板

该网站集成了命令菜单系统（CommandMenu 组件），可提供跨文档的快速导航和搜索功能。

响应式设计

该网站实现了全面的响应式设计模式。

• 移动导航：使用 MobileNav 的抽屉式导航。
• 响应式图片：用于浅色/深色主题的动态图片切换。
• 自适应布局：能够适应屏幕尺寸的灵活网格系统。

SEO 和社交集成

文档页面生成动态元数据，包括：

• Open Graph 图片：自动生成的社交媒体预览。
• Twitter 卡片：社交分享优化。
• 结构化元数据：为搜索引擎提供的全面 meta 标签。

来源：apps/www/app/(app)/page.tsx20-42 apps/www/components/command-menu.tsx apps/www/app/(app)/docs/[[...slug]]/page.tsx:35-74