架构

这个网站是一个 Next.js 16（App Router）应用，在构建时生成静态 HTML， 采用 YuTheme 设计语言，部署在 Vercel 上。没有服务器运行时。

技术栈

• Next.js 16（App Router、静态生成）
• React 19
• TypeScript
• pnpm（包管理器，通过 packageManager 固定版本）
• Turborepo 单体仓库（apps/、packages/）
• next-intl 支持七种语言，localePrefix: as-needed
• YuTheme 令牌和编辑惯例（见 design.md）
• Lucide 图标（通过 lucide-react）
• 字体：Geist Variable 和 Geist Mono Variable（通过 next/font/local）

唯一的客户端 JavaScript 是少量水合：页头的移动端菜单、滚动监听、 锚点平滑滚动和滚动显现。

结构

apps/web/src/
  app/
    [locale]/
      layout.tsx            文档外壳、字体、元数据、JSON-LD
      page.tsx              单页主页
      docs/page.tsx         文档索引
      docs/[slug]/page.tsx  单个文档页面
      globals.css           YuTheme 令牌、基础样式、动效
    sitemap.ts              所有语言的站点地图
    robots.ts
  components/
    Analytics.tsx           Umami 钩子，由环境变量启用，默认不生效
    Footer.tsx
    Header.tsx              固定页头、滚动监听、移动端抽屉
    Icon.tsx                Lucide 图标映射，类型化名称
    Reveal.tsx              通过 IntersectionObserver 实现滚动显现
    sections/
      Hero.tsx              标题 + 终端卡片
      About.tsx
      WhatIDo.tsx           卡片网格
      HowIWork.tsx
      WhereILive.tsx
      SelectedWork.tsx      公开工作列表
  data/site.ts             网站常量：URL、导航
  i18n/                    routing、请求配置、类型化导航
  lib/docs.ts              文档页面的 Markdown 管线
packages/
  content/                 docs/ 源文件，按语言读取并带英文回退
  i18n/                    语言列表 + 七种区域设置的文案
  ui/styles/               规范 YuTheme CSS、令牌参考

本地化

• 语言：en（默认、无前缀）、pt、es、fr、de、ja、zh-CN。
• 界面文案位于 packages/i18n/messages/<locale>.json。
• 文档位于 packages/content/docs/<locale>/；当某语言缺少文件时，自动 提供英文版本作为回退。
• 路由是静态的：在构建时通过 generateStaticParams 预渲染每种语言和 每个文档 slug。

文档管线

文档页面通过 packages/content/src/index.ts 读取 packages/content/docs/ 文件夹：

• 每个文档都是带前言（frontmatter）的 Markdown 文件：title、 description、order、updated；
• 应用使用 remark/rehype（GFM、标题 slug、自动链接、经过净化的 HTML） 在 /docs/<slug> 渲染，索引在 /docs；
• @ellamizuki/content 保持为应用包外的外部包 （serverExternalPackages），以便文件系统读取在生产环境正常工作。

由于集合读取的是仓库中相同且经过版本管理的文件夹，文档保持同步： 一个真实来源，两种视图（网站页面和仓库文件）。

数据流

• 构建时：Next.js 为每种语言预渲染 /、/docs、/docs/*。
• 内容预先渲染；没有服务器、没有 API、没有运行时数据。
• 分析（Umami）只有在构建时同时设置了 NEXT_PUBLIC_UMAMI_SRC 和 NEXT_PUBLIC_UMAMI_WEBSITE_ID 才会被注入。

约定

• 语义化 HTML，每页只有一个 h1。
• 章节标题有序（先 h2 再 h3），不跳级。
• 外部链接在新标签页打开，带 rel="noopener noreferrer"。
• next-intl 渲染的链接永远不会收到已带前缀的 href；语言前缀始终由 导航辅助函数添加。
• 处处尊重减少动态效果：微光、显现和过渡都由 prefers-reduced-motion 控制。