项目背景
航通社博客系统原本是一个基于Jekyll的传统静态博客，采用标准的多页面架构。本次改造的目标是将其升级为现代化的单页应用（SPA），同时保持Jekyll的静态生成优势和SEO友好性，并与图片库（/photos）的设计风格保持一致。
改造目标
核心需求
视觉统一：参照图片库的简洁设计风格，实现两栏布局，左侧固定导航栏，右侧动态内容区。
功能完善：保留博客核心功能的同时，增强用户体验，包括搜索、筛选、深色模式、评论系统等。
性能优化：使用图片CDN服务优化加载速度，支持原图开关，平衡质量与性能。
内容管理：将AIGC早报从主列表分离，建立独立入口，保持主博客内容的专注性。
设计理念
单页应用架构
改造的核心思路是在保持Jekyll静态生成的基础上，通过JavaScript实现单页应用体验。这种混合架构的优势在于：
SEO友好：每篇文章仍然有独立的URL和完整的HTML页面，搜索引擎可以正常抓取。
用户体验：在博客内部导航时，通过JavaScript动态加载内容，无需刷新页面，提供流畅的浏览体验。
渐进增强：即使JavaScript被禁用，用户仍然可以通过传统的页面跳转访问所有内容。
重定向机制
为了实现单一代码源的维护，我们采用了重定向机制。当用户直接访问文章URL时，post.html布局会通过JavaScript重定向到主页，并通过URL参数传递文章路径。主页检测到参数后，在右侧内容区加载文章详情，然后将URL更新回文章的真实路径。这样确保了：
代码复用：文章详情视图只需在home.html中维护一份代码，post.html只是简单的重定向页面。
自动同步：对文章详情页的任何修改都会自动应用到所有访问方式。
URL一致性：最终用户看到的URL仍然是文章的permalink格式，不影响分享和收藏。
技术实现
布局结构
博客采用两栏布局，左侧边栏固定280px宽度，包含Logo、搜索框、标签云、年份导航、功能开关和版权信息。右侧主内容区自适应宽度，根据当前状态显示文章列表、文章详情或静态页面。移动端自动切换为单栏布局配合汉堡菜单，侧边栏从左侧滑出，带有半透明遮罩层。
状态管理
系统维护了几个关键的全局状态变量。allPosts数组存储所有文章的元数据（不包括AIGC早报），filteredPosts数组存储当前筛选条件下的文章，currentFilter对象记录当前的筛选类型和值，displayedCount记录当前显示的文章数量用于无限滚动。
视图切换
系统有三个主要视图：文章列表视图（postsView）、文章详情视图（postView）和静态页面视图（pageView）。视图切换通过显示隐藏对应的DOM元素实现，切换时会同步更新URL、浏览器标题和History API状态，确保浏览器前进后退按钮正常工作。
筛选系统
筛选系统支持按标签、年份和关键词搜索三种方式。所有筛选函数都遵循统一的模式：首先检测并切换视图状态，确保在列表视图下操作；然后执行筛选逻辑，更新filteredPosts数组；接着清除其他筛选状态，避免冲突；最后更新URL、标题和浏览器历史记录。
从一个筛选页切换到另一个筛选页时，系统会先检测当前是否在文章页或页面视图，如果是则先返回列表视图，然后再应用新的筛选条件。这避免了视图状态混乱导致的崩溃问题。
图片优化
系统集成了Weserv图片CDN服务，对图片进行智能处理。文章列表的缩略图统一使用weserv处理（400x200尺寸，80%质量），确保快速加载。文章详情页的题图和内容图片根据原图开关状态显示，默认使用weserv处理后的图片，用户可以选择查看原图。
原图开关状态保存在localStorage中，下次访问自动恢复。切换开关时，文章详情页的图片会实时更新，使用data-original属性保存原始图片URL，切换时替换src属性。
评论系统
集成了Giscus评论系统，基于GitHub Discussions实现。每篇文章使用specific映射方式，以文章URL作为唯一标识，确保每篇文章有独立的评论区。评论系统支持GitHub OAuth登录，数据存储在仓库的Discussions中，完全免费且易于管理。
深色模式
深色模式采用GitHub风格的配色方案，与giscus评论系统完全一致。侧边栏背景使用#010409，外围背景使用#0D1117，正文区域背景使用#161b22。浅色和深色模式各使用6种颜色，确保视觉简洁统一。
深色模式默认跟随系统设置，用户手动切换后会保存选择。切换时评论系统的主题也会自动同步，使用CSS变量和data-theme属性实现全局主题切换。
标题管理
| 为了避免代码重复，创建了统一的标题管理函数。getPageTitle函数根据页面类型和值生成标题，主页标题格式为”航通社 | 你应该知道的历史、现在和未来”，筛选页格式为”标签：AIGC - 航通社”，文章页格式为”文章标题 - 航通社”。updatePageTitle函数封装document.title的设置，所有需要更新标题的地方都调用这个函数。 |
这种设计将原来分散在14处的标题设置代码统一到两个函数中，减少了约40行重复代码，确保了标题格式的一致性。
功能特性
AIGC早报专区
主博客列表自动过滤掉所有带AIGC标签的文章，在collectAllPosts函数中直接在DOM层面隐藏这些文章。搜索框下方添加了”每日AIGC早报”专门入口，点击后进入AIGC标签汇总页，该页面会重新收集包括AIGC在内的所有文章。
无限滚动
文章列表支持无限滚动加载，初始显示12篇文章，滚动到距离底部200px时自动加载更多。所有文章的元数据在页面加载时通过JSON注入，无需额外请求。滚动加载只是显示隐藏DOM元素，性能优秀。
搜索功能
实时搜索文章标题和摘要，使用300ms防抖处理避免频繁触发。搜索针对所有文章进行，不受当前显示文章数量限制。搜索结果即时显示，并更新URL参数，支持浏览器前进后退。
社交分享
文章详情页底部提供分享按钮，支持分享到微博、Twitter、Facebook，以及微信扫码分享和一键复制链接。所有按钮都有悬停效果和品牌配色。
上下篇导航
文章底部显示上一篇和下一篇的导航链接，点击后在右侧栏内加载对应文章，无需刷新页面。导航按钮显示相邻文章的标题，带有箭头图标。
配色方案
浅色模式
主背景使用#F7FAFC，次要背景使用#EDF2F7，卡片和输入框使用#FFFFFF。主文字使用#1A202C，次要文字使用#718096。Accent Color统一使用#347df8，应用于链接、按钮激活状态和强调元素。
深色模式
侧边栏背景使用#010409，外围背景使用#0D1117，正文区域背景使用#161b22。主文字使用#e6edf3，次要文字使用#8b949e。边框使用#30363d。Accent Color与浅色模式相同，使用#347df8。
配色方案参考了GitHub和Chakra UI的设计语言，确保了足够的对比度和可读性，符合WCAG无障碍标准。
移动端适配
桌面端显示完整的两栏布局，侧边栏固定在左侧。移动端（768px以下）自动切换为单栏布局，顶部显示Logo和汉堡按钮，点击汉堡按钮后侧边栏从左侧滑出，背景显示半透明遮罩层。
点击遮罩层任意位置或完成操作后，侧边栏自动关闭。所有筛选函数末尾都调用closeMobileSidebar，确保移动端用户体验流畅。
维护建议
代码结构
所有核心逻辑都在home.html中，包括状态管理、视图切换、筛选系统等。post.html和page.html只是简单的重定向页面，不包含业务逻辑。修改文章详情页或页面视图时，只需修改home.html中的对应函数。
添加新功能
如果需要添加新的筛选条件，参考handleTagClick或handleYearClick的实现模式。如果需要修改标题格式，只需修改getPageTitle函数。如果需要调整配色，修改unified-styles.css和dark-mode.css中的CSS变量。
调试技巧
浏览器控制台会输出关键的初始化信息，如”Loaded metadata for X posts”和”Blog initialized with X posts”。如果筛选或视图切换出现问题，检查currentFilter和filteredPosts的值。如果URL或标题不正确，检查History API的pushState调用。
性能考虑
所有文章的元数据在页面加载时一次性注入，避免了重复请求。文章内容通过fetch按需加载，减少初始加载时间。图片使用weserv CDN处理，大幅减少带宽消耗。无限滚动只是显示隐藏DOM元素，不涉及DOM创建，性能优秀。
已知限制
SEO考虑
虽然每篇文章都有独立的URL和HTML页面，但通过JavaScript加载的内容可能不会被所有搜索引擎完全索引。建议定期检查Google Search Console，确保重要内容被正确抓取。
浏览器兼容性
系统使用了现代JavaScript特性（如fetch、History API、CSS变量等），需要较新的浏览器支持。建议在生产环境中添加必要的polyfill，或在不支持的浏览器中回退到传统的多页面模式。
内容更新
文章元数据在页面加载时注入，如果发布新文章，用户需要刷新页面才能看到。考虑添加”检查更新”功能，或使用Service Worker实现后台更新。
总结
本次改造将航通社博客从传统的多页面架构升级为现代化的单页应用，在保持Jekyll静态生成优势的同时，大幅提升了用户体验。通过精心设计的架构和统一的代码规范，系统具有良好的可维护性和可扩展性。
改造过程中始终遵循”代码复用”和”逻辑集中”的原则，避免了重复代码和分散的业务逻辑。所有关键功能都有清晰的实现模式，便于后续维护人员理解和扩展。
希望本文档能够帮助后续维护人员快速了解系统架构和设计思路，顺利接手和改进这个博客系统。