docs(template-variables): 与 Gridea Pro 真实运行时对齐

[Tespera]

背景

之前在做 cactus / liushen / mango 主题时反复踩到同一类坑：因为 references/template-variables.md 与 Gridea Pro 引擎实际暴露的模板上下文有出入，主题作者只好用客户端做兜底（fetch /atom.xml 推断上下篇、自己 dump search-index、把分类 fallback 到 tag 等），最后产物又笨又冗余。

这次照着 backend/internal/template/types.go、backend/internal/render/jinja2_renderer.go、backend/internal/engine/{engine,page_renderer,search_builder}.go 直接对齐一次，省得后面的主题作者继续重复造轮子。

Summary

• Post 对象补字段：id / abstract / description / toc / categories / tagsString / stats / prevPost / nextPost / createdAt / updatedAt / updatedAtFormat / published
• 修正旧错：旧文档说 post.date 是字符串——其实是 time.Time（结构体里就是 time.Time 类型），展示首选 post.dateFormat；要换格式就用 {{ post.date|date:"layout" }}
• 新增对象章节：Category / PostStats / SimplePostView（prevPost / nextPost 的元素类型）
• Tag 补 slug / usedName；Memo 补 id / tags / createdAt / createdAtISO / dateFormat
• Pagination 补 currentPage / totalPages / totalPosts / hasPrev / hasNext / prevURL / nextURL，保留 prev / next 别名
• 全局变量补 category / current_tag(别名) / archives / links / commentSetting / site(config 别名)
• 新增 category.html 页面说明：引擎自动渲染每个分类到 /category/<slug>/；同时澄清「没有 categories.html」——引擎不暴露全站分类索引页和 categories 全局数组
• 新增章节《引擎自动生成的输出》：列出 /api/search.json / /feed.xml / /atom.xml / /sitemap.xml / /robots.txt / /manifest.json，连带 search.json 的 schema（[{title, link, date, tags, content}]，content 已脱 HTML）和客户端 fetch 示例
• prevPost / nextPost 语义警示（重要）：Gridea Pro 把数组前一项（更新的一篇）赋给 prevPost，与 Hexo / Hugo 习惯相反；从其他生态移植主题时别照搬「上一篇 = 更早」的标签

同步更新：

• assets/mock-data.json：首篇 mock 文章补齐新字段；新增 category 全局对象；标签补 slug
• scripts/render_test.py：补 category.html 模板分支（注入 category + 按 post.categories 过滤 posts）

影响 / 回归测试

直接跑 gridea-pro-themes 仓内已合并 + 待合并的主题：

主题	状态	模板数	通过
bitcron-pro	已合	9	9/9 ✅
liushen	已合	13	13/13 ✅
jasmine	已合	13	13/13 ✅
cactus（PR #12）	待合	12	12/12 ✅

无回归。

Test plan

• mock-data.json schema 可解析
• cactus / jasmine / liushen / bitcron-pro 全部 render_test 通过
• 维护者在自己环境复跑 scripts/render_test.py themes/<任一主题>/
• 用文档示例的 {{ post.dateFormat }} / {{ post.prevPost.title }} / /api/search.json 起一个 demo 主题，确认与 Gridea Pro 桌面客户端真实 build 输出一致

后续

文档里的语义警示（prevPost = 更新的一篇）建议未来在 Gridea Pro 主程序里做个补救：要么改命名（olderPost / newerPost），要么至少在主程序文档里加红字提示。这个 PR 不动主程序，只把现状文档化，免得新主题作者继续踩同一个坑。

🤖 Generated with Claude Code