0.3.0 是发布以来最大的一版:站点从此有了完整的导航骨架——分类索引、按年归档、每个标签和分类的独立页面——同时默认主题整体重绘,TOC 会跟随阅读位置高亮。这版也顺带修了几个会让 CI 和中文站点出问题的行为缺陷。
这一版在解决什么
此前文章模板里渲染的标签和分类链接指向 /tags/<name>/ 这类地址,但引擎从不生成这些页面——站上每个标签链接都是 404。站点也没有分类索引和归档,内容多了之后无处可逛。另外几个修复同样关键:中文标签会生成 dist/tags/%E6%8F%92%E4%BB%B6/ 这样的百分号编码目录,静态服务器解析不了(它们会先解码请求路径);site.url 未配置时 sitemap.xml 和 feed.xml 输出相对链接,CI 构建的站点提交给搜索引擎的是坏地址。
变了什么
Added
- 分类索引与归档页:通过新的
indexes配置块生成/categories/(带文章数的分类卡片)和/archives/(按年分组的文章列表),默认主题导航随之带上首页 / 分类 / 归档 / 关于。只有主题提供了对应布局才会生成,自定义主题不受影响;indexes.categories.enabled: false可关闭。索引页进sitemap.xml,但不进 RSS、导航分组和上下篇。 - 标签、分类、系列页:每个词条现在有真实页面(
/tags/<name>/、/categories/<name>/、/series/<name>/),用主题的taxonomy.html布局渲染,文章按时间倒序。之前的所有 404 都消失了。 - 全新默认主题:安静的玉绿色调、首页两栏卡片网格加粘性侧边栏(站点简介、分类、标签、归档入口)、胶囊高亮的头部导航、文章卡片上的分类标签,响应式断点覆盖到手机宽度。
- 跟随阅读位置的 TOC:
assets/toc.js高亮视口顶部所在章节(补偿粘性头部高度)、滚到底时强制高亮最后一条、TOC 自身溢出时自动滚动条目,只在有标题的页面加载,两个主题都通过.toc a.is-active控制样式。 - GitHub Pages 工作流(
.github/workflows/pages.yml):站点、引擎或主题变更时跑测试、构建examples/blog并部署,SITE_URL从仓库坐标注入。 scripts/pages-base.js:临时的构建期链接前缀工具,让示例站能在项目页路径下工作,等site.base在 URL 生成阶段生效后移除。
Fixed
- 开发服务器配置热更新可能一直用旧配置:
.mjs配置用?t=Date.now()做缓存穿透,同一毫秒内两次保存会产生相同 URL,命中 Node 的 ESM 缓存。现在改用单调递增计数器。 - 百分号编码 URL 之前会写出编码目录(
dist/tags/%E6%8F%92%E4%BB%B6/),现在输出路径解码为dist/tags/插件/,URL 和sitemap.xml保持编码。 site.url未配置时sitemap.xml与feed.xml输出相对<loc>;示例站现在从环境变量读取SITE_URL,CI 构建产出绝对链接。
升级要不要动手
直接升级,现有站点无需改配置即可继续构建。想要分类索引和归档页,在配置里加 indexes 块即可(详见配置教程);自定义主题想获得这些页面,需要提供对应布局。默认主题用户会直接看到新设计,如果之前依赖旧版视觉细节,可能需要调整自定义样式。部署到 GitHub Pages 的用户可以参考新的工作流文件,或直接看部署教程。
评论