MkDocs 双语文档站点 PRD¶

1. 文档目的¶

本文件用于定义当前仓库的 MkDocs 文档站点建设要求，作为后续 AI 或开发者统一执行的依据。

目标是让不同执行者在没有额外口头解释的情况下，仍然能够延续当前结构：仓库目录中的 README.md 和 README.zh.md 是正文来源，docs-site/ 负责站点配置、导航和发布。

本 PRD 面向 Recommender-Systems 仓库，同时保留可迁移性。迁移到其他仓库时，应优先保留“目录 README 作为内容源，MkDocs 作为导航和发布层”的方式。

2. 建设目标¶

需要建设一套独立的文档站点方案，满足以下要求：

使用 MkDocs 作为文档站点框架。
使用 i18n 方案支持中英双语。
文档站点独立放置在 docs-site/ 目录下。
英文正文统一写在各目录的 README.md。
中文正文统一写在各目录的 README.zh.md。
docs-site/docs/en 与 docs-site/docs/zh 通过符号链接接入这些 README，避免复制正文。
导航结构在中英文之间尽量保持一致。
提供可用于自动构建和部署的 GitHub Actions 工作流。
整体结构应具备通用性，便于迁移到其他仓库复用。

3. 适用范围¶

本 PRD 适用于以下场景：

为开源或内部项目搭建统一文档站点。
为代码仓库补充中英双语文档能力。
为团队沉淀可复制的文档工程模板。
为其他 AI 提供统一实现标准，降低输出差异。

本 PRD 不限定具体业务领域，也不要求绑定某种编程语言、框架或部署平台以外的复杂基础设施。

4. 总体要求¶

4.1 工程独立性¶

文档站点必须作为独立工程存在于 docs-site/ 中。
文档站点配置、导航、依赖和构建逻辑应收敛在 docs-site/ 中。
正文内容应跟随对应算法或数据集目录，使用目录级 README 维护。
不应在 docs-site/docs/ 中复制一份相同正文。
应通过符号链接让 MkDocs 读取仓库目录中的 README。

4.2 双语一致性¶

必须同时支持中文和英文。
中文和英文文档应采用平行文件组织：README.md 对应英文，README.zh.md 对应中文。
相同主题的页面必须尽量一一对应。
导航、栏目、层级和命名语义应保持一致。
不允许只完成单语结构后再以临时补丁方式拼接另一种语言。

4.3 技术统一性¶

文档框架统一使用 MkDocs。
多语言实现统一采用 i18n 方式。
方案应优先选择成熟、主流、可维护的插件与配置方式。
避免引入与核心目标无关的复杂工程化定制。

4.4 自动化要求¶

应提供标准的自动化构建与部署流程。
自动化流程应适用于 GitHub 仓库。
至少支持通过 GitHub Actions 完成文档构建和静态站点部署。
部署目标优先兼容 GitHub Pages。

5. 推荐信息架构原则¶

文档站点的信息架构应满足以下原则：

首页用于概览、入口说明和导航引导。
入门文档用于介绍快速开始、基础使用和最小上手路径。
用户指南用于组织面向使用者的主要内容。
教学类内容用于沉淀方法、流程、实践或专题说明。
项目类内容用于放置仓库相关说明、约束、协作规则或附加信息。
PRD 类内容用于放置需求说明、设计目标、执行约束等过程文档。
算法与数据集正文应优先放在对应目录的 README 中，方便读者不进入站点也能直接阅读。

说明：

上述栏目是逻辑分类，不要求绑定特定业务名称。
实际页面内容可以根据仓库主题调整，但分类思路应稳定。
若某些栏目暂时没有内容，应允许以占位页或目录说明形式存在。

6. 内容组织要求¶

6.1 语言分层¶

文档源码应按语言拆分。
中文和英文分别拥有独立入口。
每种语言均应具备独立首页。
每种语言均应具备对应的导航结构。
对算法和数据集页面，docs-site/docs/en 应链接到对应 README.md，docs-site/docs/zh 应链接到对应 README.zh.md。

6.2 页面命名原则¶

页面命名应清晰、稳定、可预测。
同一主题的中文和英文页面应保持语义对应。
仓库目录内固定使用 README.md 和 README.zh.md，不要使用 README.en.md。
命名应优先表达文档用途，而不是使用随意缩写。
不应依赖当前仓库的临时术语作为唯一组织依据。

6.3 导航原则¶

导航应反映内容结构，而不是仅反映文件存放位置。
首页、入门、用户指南、专题内容、项目说明、PRD 内容等应有清晰分组。
导航层级不宜过深。
中英文导航结构应尽量镜像一致。
导航项可以指向 docs-site/docs/ 中的符号链接文件。符号链接目标应指向仓库中唯一的 README 正文。

6.4 占位与扩展¶

初始版本允许使用简短页面建立结构骨架。
算法和数据集目录不应只放空占位，应至少说明为什么有这个方法、核心想法、MovieLens 上怎么练、第一版代码先做什么。
后续扩展时应优先补充对应目录 README，不应在 MkDocs 目录复制正文。

7. 配置要求¶

7.1 MkDocs 配置¶

实现方案中应包含完整的 MkDocs 配置，至少应覆盖：

站点基础信息
主题配置
导航配置
多语言配置
Markdown 扩展配置
插件配置
静态资源配置
对符号链接接入内容的路径约定

7.2 i18n 配置¶

多语言方案必须满足以下要求：

明确声明支持的语言集合。
明确默认语言。
明确不同语言页面的映射关系或组织方式。
能支持中文与英文切换。
能支持未来继续扩展更多语言，而无需推翻现有结构。
当前语言映射为：英文 README.md，中文 README.zh.md。

7.3 可读性要求¶

配置文件应结构清晰，分段合理。
命名和注释应便于维护者理解。
不应把关键逻辑隐藏在难以追踪的脚本拼装中。

8. 自动化与部署要求¶

8.1 GitHub Actions¶

必须提供文档站点自动化工作流，至少包括：

检出仓库代码
安装构建依赖
构建 MkDocs 站点
部署生成后的静态文件

8.2 工作流质量要求¶

工作流应尽量简单、稳定、可维护。
命名应清晰，便于团队成员理解用途。
不应为了追求复杂能力而显著增加维护成本。
应优先采用 GitHub 官方或社区稳定方案。

8.3 部署目标¶

优先面向 GitHub Pages。
若后续迁移到其他静态托管平台，结构上也应尽量兼容。
部署方案应尽量减少与业务运行环境的耦合。

9. 非功能要求¶

9.1 通用性¶

输出结果应具备模板属性。
不应把当前仓库的个别业务术语写死到基础方案中。
同一套结构应能迁移到其他项目继续使用。

9.2 可维护性¶

新成员应能快速理解文档工程组织方式。
后续新增页面时，不应频繁改动核心结构。
中英文内容维护方式应清晰明确。

9.3 一致性¶

中英文结构一致。
页面风格一致。
配置风格一致。
自动化流程命名与职责一致。

9.4 可扩展性¶

允许未来增加新栏目。
允许未来增加更多语言。
允许未来增强主题、搜索、SEO、版本化等能力。
但本次实现不要求一次性覆盖所有高级功能。

10. 交付物要求¶

执行该 PRD 时，至少应交付以下内容：

docs-site/ 文档工程目录
MkDocs 主配置文件
支持 i18n 的多语言配置
中文文档入口页或入口链接
英文文档入口页或入口链接
各算法和数据集目录的 README.md 与 README.zh.md
docs-site/docs/en 与 docs-site/docs/zh 下指向 README 的符号链接
静态资源目录
GitHub Actions 工作流文件
简要维护说明

11. 验收标准¶

满足以下条件时，视为该任务完成：

仓库中存在独立的 docs-site/ 文档站点工程。
文档站点基于 MkDocs 构建。
文档站点支持中文与英文两种语言。
多语言实现基于 i18n 方案，而非手工复制拼装。
中英文首页均可作为独立入口使用。
中英文导航结构基本一致。
站点可通过 GitHub Actions 自动构建。
站点可通过 GitHub Actions 自动部署到 GitHub Pages 或兼容静态托管目标。
算法和数据集正文只有一个维护源，不在 MkDocs 目录重复复制。
目录、配置和内容组织方式具备复用价值。
其他 AI 或开发者可基于该结构继续扩展，而无需重新设计底层方案。

12. 实施约束¶

执行者在实现时应遵守以下约束：

不要把方案做成仅适用于某一个仓库的特殊实现。
不要把配置写得过于耦合或难以迁移。
不要省略双语结构设计。
不要使用 README.en.md，英文统一使用 README.md。
不要在 docs-site/docs/ 中复制算法和数据集正文。
不要只完成页面文件而缺少自动化部署能力。
不要把目录结构设计成依赖执行者个人习惯才能理解。
不要引入明显超出需求范围的复杂系统。

13. 对执行者的明确指令¶

请基于本 PRD，为目标仓库设计并实现一套标准化文档站点方案。实现要求如下：

使用 MkDocs
使用 i18n 支持中英双语
文档站点工程放置于 docs-site/
算法和数据集正文放置于对应目录 README
MkDocs 通过符号链接接入 README，保持 DRY
输出结构清晰、可维护、可迁移
提供基础导航和可阅读的初始页面
提供 GitHub Actions 自动构建与部署流程
优先兼容 GitHub Pages
尽量保持实现简单、稳定、通用

14. 期望结果¶

最终应得到一套独立、规范、支持中英双语、可自动部署、适合长期维护的 MkDocs 文档站点骨架。

该骨架应满足以下目的：

当前仓库可直接使用
未来可持续扩展
可作为其他仓库的模板
可作为其他 AI 的统一执行输入
尽量减少不同执行者之间的结果偏差