Serendipity
edbf78f236
- Halo Plugin 后端（Java/Gradle），含 DarkModePlugin 主类和测试 - Vue 3 + TypeScript 前端 UI，包含主题切换组件和设置页面 - 暗色模式 CSS 变量和覆盖样式（布局/编辑器/表单/滚动条等） - 设计文档和调查文档 - Halo 插件/主题开发 Agent Skills Co-Authored-By: Claude <noreply@anthropic.com>
84 lines
4.6 KiB
Markdown
84 lines
4.6 KiB
Markdown
# 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
|
|
|
|
```html
|
|
<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`.
|
|
|
|
```yaml
|
|
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.**
|
|
|
|
- index: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/template-variables/index_.md
|
|
- post: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/template-variables/post.md
|
|
- page: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/template-variables/page.md
|
|
- archives: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/template-variables/archives.md
|
|
- tag: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/template-variables/tag.md
|
|
- tags: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/template-variables/tags.md
|
|
- category: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/template-variables/category.md
|
|
- categories: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/template-variables/categories.md
|
|
- author: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/template-variables/author.md
|