Files

T

Serendipity edbf78f236 feat: 初始化 Halo 暗色模式插件

- Halo Plugin 后端（Java/Gradle），含 DarkModePlugin 主类和测试
- Vue 3 + TypeScript 前端 UI，包含主题切换组件和设置页面
- 暗色模式 CSS 变量和覆盖样式（布局/编辑器/表单/滚动条等）
- 设计文档和调查文档
- Halo 插件/主题开发 Agent Skills

Co-Authored-By: Claude <noreply@anthropic.com>

2026-08-06 21:03:00 +08:00

4.6 KiB

Raw Permalink Blame History

Template Route Mapping & Template Variables

Template Route Mapping

Template file	URL path	Main variables	`_templateId`
`templates/index.html`	`/`	`posts`	`index`
`templates/post.html`	`/archives/:slug`	`post`	`post`
`templates/page.html`	`/:slug`	`singlePage`	`page`
`templates/archives.html`	`/archives[/:year[/:month]]`	`archives`	`archives`
`templates/tags.html`	`/tags`	`tags`	`tags`
`templates/tag.html`	`/tags/:slug`	`tag`, `posts`	`tag`
`templates/categories.html`	`/categories`	`categories`	`categories`
`templates/category.html`	`/categories/:slug`	`category`, `posts`	`category`
`templates/author.html`	`/authors/:slug`	`author`, `posts`	`author`

Route prefixes (/archives, /tags, /categories) can be customized by users in Console system settings.

Error Templates

Halo supports custom error pages under templates/error/:

Template file	Status code match
`templates/error/404.html`	Exact 404
`templates/error/4xx.html`	Any 4xx client error (fallback)
`templates/error/500.html`	Exact 500
`templates/error/5xx.html`	Any 5xx server error (fallback)
`templates/error/error.html`	Catch-all default

Resolution order for a 404: 404.html → 4xx.html → error.html

Error template variables

<div>
  <h2 th:text="${error.status}">404</h2>
  <p th:text="${#strings.defaultString(error.title, 'Error')}"></p>
  <p th:if="${not #strings.isEmpty(error.detail)}" th:text="${error.detail}"></p>
</div>

Variable	Type	Description
`error.status`	number	HTTP status code
`error.title`	string	Error title
`error.detail`	string	Detailed message
`error.instance`	string	Error instance URI
`error.type`	string	Error type URI

Custom Templates

Register additional rendering templates for posts, single pages, or category archives via spec.customTemplates in theme.yaml. Supported types: post, page, category.

spec:
  customTemplates:
    post:
      - name: Documentation
        file: post_documentation.html # create under templates/

After modifying theme.yaml, click "Reload Theme Configuration" on the theme page in Console.

Key Notes

Use th:utext (unescaped) to render post/page body content — never th:text.
List variables (posts, archives, etc.) are UrlContextListResult; use .hasPrevious()/.hasNext()/.prevUrl/.nextUrl for pagination.
post.content.content is only available automatically in post.html; in other templates fetch it separately via postFinder.content(postName).

Online Docs

Halo's VO types (field names, nested structures) change across versions. Do not guess field names from training data. Always fetch the doc for the relevant template before accessing specific fields on template variables.

4.6 KiB Raw Permalink Blame History