更新日志 发布于 2026-11-04

xfmpress v0.3.0:分类归档、标签页与全新默认主题

4 分钟阅读 # xfmpress# 更新日志

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 的用户可以参考新的工作流文件,或直接看部署教程。

评论