baixinpan.github.io 迭代优化文档

本文档基于当前 baixinpan.github.io 项目源码、内容结构和 UI/UX 检查结果整理，用于后续排期、开发和验收。

当前站点是一个基于 Jekyll 的个人技术博客，核心场景包括：

• 展示个人身份、技术方向和站点入口。
• 发布技术文章、工具链记录、项目经验和历史教程。
• 通过归档、标签、RSS、评论和社交链接帮助读者继续浏览或联系作者。
• 继续承接原 leopardpan.github.io 项目的内容资产与模板影响力。

1. 当前现状

1.1 已具备的能力

• 首页已有文章卡片列表，包含日期、标题、摘要、标签和阅读全文入口。
• 文章页已有标题、发布时间、阅读统计、标签、正文、目录、上一篇/下一篇和评论区。
• 归档页按年份展示全部文章。
• 标签页提供标签云和标签分组文章列表。
• 站点已包含基础 SEO 信息：title、description、canonical、OG、Twitter Card、RSS。
• 已具备移动端顶部导航、跳过正文链接、焦点态和 prefers-reduced-motion 兼容。
• README 已记录项目沿革、本地运行、目录说明和发布方式。

1.2 当前主要问题

• 首页和文章页缺少站内搜索，用户只能通过归档和标签找内容。
• 标签入口不够精准，首页卡片标签只跳转到标签页，没有直达对应标签分组。
• 旧文章较多，文章页需要确保发布时间足够清晰；不额外增加时效性提示，由读者结合发布时间判断。
• 文章页已有上一篇/下一篇，但同主题路径主要通过 tag 完成，需要让 tag 可点击并能过滤同 tag 文章。
• UI 风格已现代化，但色彩体系偏单一，强调色主要依赖棕色系。
• 部分移动端触控目标低于 44px，仍有提升空间。
• 评论、统计、第三方脚本依赖外部服务，缺少前端层面的降级提示。

2. 设计原则

后续迭代建议遵循以下原则：

2.1 内容优先

这是技术博客，不是营销官网。页面设计应优先保证文章可读、信息可找、入口清晰。视觉增强服务于阅读和检索，不做过多装饰。

2.2 保留个人站气质

当前封面、头像、左侧视觉面板和温暖色调已经形成识别度。后续不建议大范围重写主题，而是在现有风格上增强层级、状态和控件。

2.3 对旧内容负责

站点有 2015、2016、2020 年的历史教程。旧内容是资产，但需要通过发布时间、适用状态和提示语降低误用风险。

2.4 静态优先

项目部署在 GitHub Pages，优先选择无需后端的方案，例如 Jekyll 构建期生成 JSON、前端本地搜索、静态相关文章列表。

2.5 可访问性优先级不降低

所有新增控件都要满足：

• 文字对比度足够。
• 可键盘访问。
• 焦点态清晰。
• 点击区域至少 44px。
• 不只依赖颜色表达状态。

3. 迭代优先级总览

4. 第一阶段：检索与内容可信度

4.1 新增站内搜索

背景

当前用户只能通过首页文章列表、归档和标签查找内容。对于技术博客，读者通常带着明确问题进入，例如 “Jekyll”、“Hexo”、“GitHub Pages”、“Markdown 工具”。搜索是高频入口。

建议方案

优先采用静态搜索：

• 构建 search.json，由 Jekyll 输出文章标题、摘要、标签、日期和 URL。
• 前端使用轻量 JS 读取 search.json。
• 初期可使用原生字符串匹配，后续再升级 Lunr.js。
• 搜索框放在首页文章列表上方。
• 移动端搜索框宽度铺满，桌面端与文章列表最大宽度一致。

页面表现

首页文章列表区域增加：

• 搜索输入框。
• 搜索清空按钮。
• 搜索结果数量。
• 无结果状态。

搜索结果卡片展示：

• 标题。
• 日期。
• 标签。
• 摘要。
• 匹配关键词高亮。

验收标准

• 输入关键词后能实时过滤文章。
• 搜索为空时恢复默认文章列表。
• 无结果时展示“没有找到相关文章”的空状态。
• 输入框可键盘聚焦，焦点态明显。
• 移动端输入框高度不低于 44px。

涉及文件

• index.html
• js/main.js
• css/main.css
• 新增 search.json

4.2 标签深链优化

背景

首页文章卡片上的标签目前只跳转到 /tags，读者还需要在标签页里再次寻找对应标签。

建议方案

将文章卡片标签链接从：

/tags

调整为：

/tags#

需要注意 post.tags 可能是数组，旧文章里也可能使用 tag 字段。建议统一转换：

• 如果是数组，逐个展示标签。
• 如果是字符串，兼容展示一个标签。
• 标签页锚点继续使用 slugify。

验收标准

• 首页点击标签后能定位到标签页对应分组。
• 多标签文章能展示多个标签。
• 中文标签锚点能正常工作。
• 标签点击区域不低于 44px。

涉及文件

• index.html
• tags.html
• css/main.css

4.3 发布时间可见性

背景

站点包含多篇多年以前的技术文章。文章页已经显示发布时间，读者可以结合发布时间自行判断内容适用性。

建议方案

不新增旧文时效提示卡，避免干扰阅读。保留文章页发布时间，并确保发布时间在文章标题下方清晰可见。

页面表现

文章页标题下方展示发布时间，格式为 YYYY-MM-DD。

验收标准

• 每篇文章标题下方都能看到发布时间。
• 发布时间在移动端和桌面端都不被遮挡。
• 不新增“历史文章”“过期”等额外提示。

涉及文件

• _layouts/post.html

5. 第二阶段：阅读路径与移动端体验

5.1 Tag 过滤同主题文章

背景

当前文章页只有上一篇/下一篇，路径是按时间组织的。用户更自然的同主题浏览方式是点击文章 tag，然后查看同 tag 文章。

建议方案

文章页中的 tag 改为可点击链接，跳转到标签页并过滤对应 tag。

页面表现

文章页 tag 使用小型标签按钮，点击后进入 /tags#tag-name。标签页根据 hash 只展示对应 tag 分组，并提供“查看全部标签”入口。

验收标准

• 文章页 tag 可点击。
• 点击 tag 后标签页只展示同 tag 文章。
• 标签页有返回全部标签的入口。
• 没有 tag 的文章不显示空控件。

涉及文件

• _layouts/post.html
• tags.html
• js/main.js
• css/main.css

5.2 移动端触控目标优化

背景

当前部分按钮和导航项高度为 38px，低于移动端推荐触控面积。

建议方案

统一交互控件尺寸：

• 移动端导航链接 min-height 调整为 44px。
• 标签、阅读全文、分页、社交链接调整到 44px。
• 控件之间保持至少 8px 间距。

验收标准

• 手机端所有主要点击区域不低于 44px。
• 横向导航仍可滚动，不产生页面级横向滚动。
• 控件增大后不遮挡首屏封面内容。

涉及文件

• css/main.css

5.3 文章类型与状态标签

背景

当前标签更多是主题分类，缺少内容类型。用户无法一眼区分“教程”“工具记录”“模板说明”“项目日志”。

建议方案

新增 front matter：

type: tutorial

可选值：

• tutorial：教程。
• note：笔记。
• project：项目。
• release：迭代记录。
• archive：历史归档。

在首页卡片和文章页元信息中展示类型标签。

验收标准

• 支持没有 type 的旧文章，不报错。
• 有 type 的文章能在首页和文章页显示类型。
• 类型标签与普通主题标签视觉上有区分。

涉及文件

• index.html
• _layouts/post.html
• css/main.css

6. 第三阶段：视觉体系与降级体验

6.1 色彩系统扩展

背景

当前主题色以暖米色、棕色、深色封面为主，个人气质明确，但信息状态不够丰富。

建议方案

在保留现有主色基础上增加语义色：

• --info：技术说明、提示。
• --success：仍适用、已维护。
• --warning：历史文章、注意事项。
• --danger：过期、不可用。
• --code-accent：代码和技术标签。

这些颜色只用于信息状态和控件，不大面积改动背景。

验收标准

• 色彩不破坏当前站点气质。
• 每个状态不仅依赖颜色，还配合文字说明。
• 浅色背景下文字对比度满足阅读要求。

涉及文件

• css/main.css

6.2 独立搜索结果页

背景

第一阶段可以先做首页内搜索。若文章继续增加，建议升级为独立搜索页。

建议方案

新增 search.html：

• 支持 URL query，例如 /search?q=jekyll。
• 搜索结果可被分享。
• 搜索页提供热门标签和最近文章。

验收标准

• 访问 /search?q=xxx 能直接显示搜索结果。
• 空 query 时展示搜索入口、热门标签和最近文章。
• 无 JS 或 JS 加载失败时仍有基本说明。

涉及文件

• 新增 search.html
• search.json
• js/main.js
• css/main.css
• _config.yml

6.3 评论与统计降级体验

背景

当前评论和统计依赖 Twikoo、Busuanzi、百度统计、Google Analytics 等外部服务。如果脚本加载失败，页面缺少明显反馈。

建议方案

• 评论容器加载中展示占位文案。
• 超时后展示“评论暂时不可用，可通过邮件联系”。
• 阅读统计加载失败时隐藏空数字，避免显示残缺文案。
• 外部脚本保持 async/defer，避免阻塞正文。

验收标准

• 评论脚本失败时页面不出现空白大块。
• 阅读统计失败时不显示“阅读 次”这类残缺文本。
• 正文渲染不被第三方脚本阻塞。

涉及文件

• _includes/comments.html
• _includes/head.html
• _layouts/post.html
• js/main.js

7. 建议实施顺序

第 1 周

完成搜索、标签深链、旧文提示。

交付物：

• search.json
• 首页搜索控件
• 标签直达锚点
• 文章时效提示组件

第 2 周

完成相关文章、移动端触控尺寸、文章类型标签。

交付物：

• 相关文章组件
• 统一按钮和标签触控尺寸
• 文章类型展示

第 3 周

完成色彩系统扩展、搜索页、评论/统计降级。

交付物：

• 补充语义色 token
• 独立搜索页
• 外部服务失败状态

8. 验收清单

8.1 UI 验收

• 首页、归档、标签、文章页在 375px、768px、1440px 下无横向滚动。
• 移动端主要交互区域不低于 44px。
• 焦点态清晰可见。
• 标签、按钮、提示卡的文字不溢出。
• 色彩状态不只依赖颜色表达。
• 文章正文行宽保持可读，桌面端不超过约 75 个中文/英文混合字符的视觉宽度。

8.2 功能验收

• 搜索能覆盖标题、摘要、标签。
• 标签能从首页直达标签页对应分组。
• 旧文章能自动显示时效提示。
• 相关文章按标签匹配，且不包含当前文章。
• 评论和统计失败时页面仍然完整可读。

8.3 性能验收

• 首页首屏图片使用合适尺寸，后续可补 WebP/AVIF。
• 非关键脚本不阻塞正文渲染。
• 搜索索引体积可控，文章数量较少时无需引入过重依赖。
• 动画尊重 prefers-reduced-motion。

8.4 SEO 与分享验收

• 每篇文章有稳定 canonical URL。
• 搜索页如上线，应避免低质量 query 页面被索引，可根据情况添加 noindex。
• OG 图片路径正确。
• RSS 正常生成。

9. 风险与注意事项

• 旧文章 front matter 字段可能不统一，新增类型或状态时要兼容空值。
• 中文标签经过 slugify 后可能出现不可预期锚点，开发时需要实际构建验证。
• GitHub Pages 的 Jekyll 插件有限，优先使用原生 Liquid 和静态文件。
• 不要大幅重写头像翻转动画，这是当前主题历史识别的一部分。
• 第三方统计和评论脚本可能受网络影响，前端要允许失败。

10. 后续可选方向

• 增加“项目”页面，集中展示个人项目、工具和 GitHub 仓库。
• 增加“精选文章”模块，把仍有价值的历史内容从时间流中提出来。
• 增加“更新日期”字段，区分发布时间和最近维护时间。
• 为文章增加封面图，但不要让图片喧宾夺主。
• 为技术教程增加版本表，例如工具版本、系统环境、适用年份。