本站
本站架构概览
本站的目录职责、四类内容集合、路由结构和静态构建链路。
本文目录
这个页面说明站点的整体结构，方便在新增页面、内容类型或功能时判断修改应该落在哪一层。
分层
src/
├── content/ # 内容源：Markdown / MDX + frontmatter
├── components/ # 可复用 UI，按 common / layout / 模块拆分
├── layouts/ # 内容型页面的共同结构
├── pages/ # 路由、robots.txt、rss.xml
├── scripts/ # 主题、导航、滚动与指针动效（原生 TypeScript）
├── assets/ # Nekotail wordmark SVG
├── styles/ # fonts、tokens、typography、effects、global、redesign
├── lib/ # 内容查询、格式化、SEO 构造函数
└── content.config.ts # 四类内容的 Zod Schema约束是：页面不直接写重复的 SEO 逻辑；布局不硬编码颜色和尺寸；组件不读取文件系统；内容不包含页面路由实现。视觉层只在 tokens.css 定义两套主题的语义变量，在 global.css 与 effects.css 中按语义变量组合，不在页面内散落颜色和尺寸。
四类内容
blog：有发布时间和更新时间的文章，支持标签、草稿、RSS；projects：项目状态、技术栈、外部链接和演进记录；knowledge：按category分组，通过parent形成层级，通过related建交叉引用；lab：交互实验的入口，正文用 MDX，可以导入 Lab 专属组件。
每类内容有独立 Schema，字段在 src/content.config.ts 中校验。这样新增文章时不需要修改页面代码，也不会让博客字段污染项目或实验模型。
视觉层
tokens.css定义SIGNAL与ELYSIUM两套主题：颜色、字体、间距、层级和动效缓动都是语义变量；当前页面固定启用ELYSIUM，redesign.css负责最终的工业档案外观覆盖。- 首页使用短刊头、蓝色信号带、纸面主文卡和精简 feed；
Wordmark.astro将src/assets/nekotail.svg以currentColor内联渲染，不直接引用角色图；主文卡底图是public/media/中经过裁切调色的抽象工程环。 - 背景纹理由
BaseLayout.astro中的等高线 SVG、点状云与像素块组成；redesign.css还提供列表页出血描边字、博客双栏、卡片小圆角、胶囊标签、文章阅读面板和 H2 档案铭牌。 fonts.css声明本地字体，当前中文使用 Noto Sans SC（SIL OFL）。global.css负责布局与组件外观，typography.css只处理正文和代码，effects.css集中加载序列、reveal、主题擦除、代码复制等效果。scripts/site.ts处理主题持久化、移动导航、滚动进度、TOC scrollspy、代码复制和指针效果；没有 React / Vue / Svelte。- 所有动效在
prefers-reduced-motion: reduce下回退为静态显示，正文不依赖 JavaScript 渲染。
路由
| 路径 | 作用 |
|---|---|
/ |
个人主页与模块入口 |
/blog/、/blog/[slug]/ |
文章列表与详情 |
/blog/tags/[tag]/ |
标签归档 |
/projects/、/projects/[slug]/ |
项目列表与详情 |
/knowledge/、/knowledge/[...slug]/ |
知识库分类与文档 |
/lab/、/lab/[slug]/ |
实验列表与详情 |
/search/ |
Pagefind 搜索界面 |
/rss.xml、/robots.txt、/sitemap-index.xml |
订阅与抓取端点 |
所有内容页面通过 getStaticPaths 在构建时生成；没有服务端运行时路由。
渲染链路
- Astro 读取内容集合，Zod 校验 frontmatter；
- 页面通过
src/lib/content.ts获取已排序或已过滤的数据； - 布局调用
src/components/common/Seo.astro生成 metadata 和 JSON-LD； - Astro 输出静态 HTML；
pagefind --site dist在构建产物上生成搜索索引。
正文必须出现在 HTML 中，不能依赖客户端 JavaScript 渲染；这是 SEO 和 GEO 的底线。