1. 产品摘要
youkechuang.cn 是一个以个人长期内容沉淀为核心的网站。当前网站由 GitSite 生成， 通过 Markdown 维护主体内容，通过静态资源目录承载图片、脚本、样式和独立工具。
网站现有内容分为三类：第一类是《我的1/3人生》这样的长篇书籍式内容；第二类是博客文章， 用于承载阶段性思考、读书笔记和主题复盘；第三类是新合入的 Maphub 地图工具， 用互动方式扩展网站的产品形态。
2. 用户与场景
| 用户类型 | 主要诉求 | 典型路径 | 产品应提供的价值 |
|---|---|---|---|
| 熟人、朋友、合作方 | 快速了解作者经历、兴趣、表达方式 | 首页 → 人生记录 → 博客 | 清晰的个人身份表达和可信的内容积累 |
| 搜索访问者 | 通过文章解决具体问题或阅读主题观点 | 搜索页落地 → 相关文章 → 站内继续浏览 | 稳定 URL、良好 SEO、内容结构清楚 |
| 工具使用者 | 打开地图工具，进行省份识别和挑战 | 首页/导航 → 地图工具 → 随机挑战 | 直接可用、加载快、移动端可操作 |
| 未来协作者 | 理解仓库结构并继续开发 | 产品文档 → 源码目录 → 本地构建 | 明确的信息架构、开发约定和验收标准 |
3. 定位与目标
3.1 产品定位
网站定位为作者个人长期公开空间。它不是一次性的个人名片，也不是只服务单篇文章分发的博客， 而是一个长期维护的内容系统。网站需要同时满足“可阅读”“可检索”“可扩展”“可部署”四个要求。
3.2 阶段目标
- 短期目标：保证现有内容稳定可访问，新增地图工具入口，形成清晰导航。
- 中期目标：补齐文档、内容分类、SEO 信息和访问统计，让网站具备持续运营基础。
- 长期目标：沉淀更多专题、工具和作品，使网站成为作者个人知识与产品能力的公开索引。
3.3 非目标
当前阶段不追求复杂后台、用户账户、服务端数据库和重型前端框架。静态站点方案符合个人网站的维护成本要求， 后续只有在明确需要动态能力时再引入服务端组件。
4. 信息架构
当前站点以 GitSite 的内容模型为基础：书籍、博客、页面和静态资源各自独立。导航由
source/site.yml 控制，发布后生成静态 HTML 文件。
| 路径 | 用途 | 维护方式 | 发布后地址 |
|---|---|---|---|
source/README.md |
首页内容 | Markdown + 内嵌 HTML | / |
source/books/onethird/ |
《我的1/3人生》章节内容 | Markdown 文件夹结构 | /books/onethird/index.html |
source/blogs/all/ |
博客文章集合 | 按日期和标题维护目录 | /blogs/all/index.html |
source/static/maphub/ |
地图互动工具 | 独立静态应用 | /static/maphub/index.html |
source/static/docs/ |
项目产品文档 | 独立 HTML + CSS | /static/docs/product.html |
5. 功能模块
首页模块
负责承接首次访问，展示核心内容入口，包括《我的1/3人生》、博客入口和后续可扩展的作品卡片。 首页应保持轻量，重点是让用户快速判断“这个网站有什么”。
长篇内容模块
面向连续阅读场景，使用书籍目录、章节页、上一篇/下一篇等结构。适合人生记录、教程、专题写作。
博客模块
面向时间线和主题沉淀，文章可被搜索索引收录。当前首页通过脚本读取博客索引并展示最新文章。
Maphub 工具模块
面向互动体验，用户可以点击中国省级行政区，查看名称、区域、行政中心，并使用随机挑战模式。
搜索模块
GitSite 生成浏览器端搜索索引，适合静态站点的全文检索。后续需要关注索引大小和中文搜索体验。
文档模块
为产品、设计、开发和运营提供说明文档。文档采用静态 HTML，避免生成器对复杂版式产生影响。
6. Maphub 集成
Maphub 已作为独立静态应用合入主站，目录为 source/static/maphub/。
这种集成方式的优点是边界清晰、上线简单、对 GitSite 主题侵入小。
6.1 当前能力
- 使用本地 Leaflet 文件和本地 GeoJSON 数据，不依赖第三方在线地图瓦片。
- 点击省级行政区后显示名称、类型、区域和行政中心。
- 使用
localStorage保存已发现省份，刷新后保留进度。 - 提供随机挑战按钮，适合学习和小游戏场景。
- 包含独立文档中心，便于记录后续地图产品迭代。
6.2 主站关系
主站只通过导航链接进入 Maphub，不共享主站布局、样式和脚本。这样可以避免地图工具的布局样式影响博客和书籍页面。 后续如果需要更强的一体化体验，可以增加统一顶部栏，但不建议把地图逻辑拆入 GitSite 主题。
| 资源 | 仓库路径 | 职责 |
|---|---|---|
| 入口页 | source/static/maphub/index.html |
页面结构和资源加载 |
| 交互脚本 | source/static/maphub/script.js |
地图渲染、点击选择、挑战状态和本地存储 |
| 视觉样式 | source/static/maphub/styles.css |
地图布局、侧栏、按钮、响应式样式 |
| 地图数据 | source/static/maphub/data/ |
中国省级行政区边界数据 |
| Leaflet | source/static/maphub/vendor/leaflet/ |
地图渲染库和样式 |
7. 内容策略
7.1 内容分层
- 核心内容：人生记录、长期项目、系统性教程。应优先放入书籍结构。
- 流动内容：读书笔记、阶段总结、观点文章。应优先放入博客结构。
- 工具内容：地图、实验、小应用。应放入
source/static/下独立维护。 - 说明内容：产品文档、开发说明、运营计划。应放入文档目录，避免混入面向普通读者的正文。
7.2 写作规范
文章标题应清楚描述主题，摘要应说明读者能获得什么。长文应使用稳定的章节结构， 避免只按写作时间堆叠。技术文章需要保留必要上下文、运行环境和结论。
7.3 首页内容策略
首页应控制信息密度，重点展示最值得访问的入口。建议把“地图工具”作为第三张卡片加入首页内容区， 而不只依赖顶部导航。这样可以提高新工具的曝光率。
8. 体验设计
网站整体体验应保持阅读优先。正文页面需要高可读性，工具页面需要高可操作性，文档页面需要高可扫描性。 三类页面可以视觉上有所区别，但导航和命名应保持一致。
| 页面类型 | 设计重点 | 不建议做法 |
|---|---|---|
| 首页 | 入口明确、信息简洁、最新内容可见 | 堆叠过多说明文字，导致用户找不到入口 |
| 书籍页 | 目录稳定、章节切换清楚、正文舒适 | 频繁改 URL 或破坏章节顺序 |
| 博客页 | 标题清晰、发布时间明确、移动端可读 | 标题过泛、正文缺少结构 |
| 工具页 | 首屏可操作、反馈明确、状态可保存 | 把说明文字放在操作区之前，延迟用户进入工具 |
| 文档页 | 目录固定、表格清楚、章节完整 | 没有目录或只有零散段落 |
9. 技术方案
9.1 技术栈
- 站点生成：GitSite CLI。
- 内容格式：Markdown、YAML、HTML、CSS、JavaScript。
- 地图能力：Leaflet + 本地 GeoJSON。
- 部署方式：GitHub Actions 构建并部署 GitHub Pages，同时保留云存储同步能力。
9.2 目录约定
| 目录 | 说明 | 维护建议 |
|---|---|---|
source/ |
站点源内容根目录 | 内容和静态资源都从这里进入构建流程 |
source/site.yml |
站点配置、导航、搜索、评论、统计、页脚 | 改导航和集成配置时优先检查这里 |
source/static/ |
构建时原样复制的静态资源 | 适合放图片、脚本、工具、独立文档 |
themes/default/ |
GitSite 默认主题子模块 | 尽量不直接改子模块；主题能力不足时优先在主项目绕开 |
_site/ |
本地构建产物 | 不作为源文件维护，发布前可重新生成 |
9.3 集成注意事项
当前主题版本缺少 GoatCounter 分析模板，因此 source/site.yml 中暂时注释了
provider: goatcounter。如果后续要恢复统计，有两个更稳妥的方案：
升级或固定一个支持 GoatCounter 的主题版本；或者在主站自定义静态脚本位置添加统计代码。
10. 构建与发布
10.1 本地构建
本地构建命令为：
gitsite-cli build -o _site
构建成功后，静态文件会生成到 _site/。本地预览可以使用任意静态服务器，
当前验证使用地址为 http://localhost:8000/。
10.2 发布流程
source/、配置和必要文档。
_site。
10.3 发布前检查
- 首页、博客、书籍、地图工具至少各访问一次。
- 确认新增静态资源路径不使用本地绝对路径。
- 确认导航链接为站点根路径下的可访问 URL。
- 确认构建没有模板缺失或脚本异常。
11. 指标体系
静态站点不一定需要复杂埋点。建议优先恢复轻量访问统计，再对 Maphub 单独增加前端事件统计。 统计目标应服务内容迭代，不应为了数据而牺牲页面性能和隐私边界。
12. 迭代路线
内容入口完善
在首页增加 Maphub 卡片；补充站点产品文档入口；检查博客标题、摘要和封面资源。
体验与 SEO 优化
优化移动端首页卡片、文章元信息、站点地图、分享标题和结构化数据。
工具与专题扩展
将 Maphub 扩展为可持续迭代的工具系列，并围绕地图、学习、产品实验形成专题页。
13. 风险与治理
| 风险 | 影响 | 处理建议 |
|---|---|---|
| 主题子模块能力不完整 | 配置某些集成时构建失败 | 固定主题版本，避免直接修改子模块；必要时 fork 主题 |
| 静态资源体积增长 | 影响加载速度和构建产物大小 | 压缩图片和数据文件，工具资源按目录隔离 |
| 内容路径变动 | 外链和搜索收录失效 | 发布后尽量保持 URL 稳定，改路径时提供跳转方案 |
| 工具页面和主站风格割裂 | 用户感知为不同产品 | 保留独立交互，同时增加统一导航或返回主站入口 |
14. 验收标准
- 产品文档以 HTML 形式存在，并可通过浏览器直接访问。
- 文档包含清晰目录，目录链接可以跳转到对应章节。
- 文档覆盖产品定位、用户场景、信息架构、功能模块、技术方案、发布流程和迭代计划。
- 桌面端目录固定在左侧，正文卡片清晰；移动端自动变为单列布局。
- 本地构建通过，发布产物中包含该文档和相关 CSS。