Add halo-theme-dev skill & theme templates

Add a new .agents/skills/halo-theme-dev skill providing Halo theme development resources: two theme templates (theme-vite and theme-minimal) with theme.yaml/settings, Vite config, package.json, CSS and JS assets, and a full set of Thymeleaf template files/partials. Include comprehensive reference docs (structure & config, finder APIs, global variables, annotations, static resources, packaging, official plugins, thymeleaf tips) and an agents/openai.yaml interface. Also update project files: modify package.json, update tsconfig.json, add skills-lock.json, rename vite-env.d.ts and remove obsolete src/main.ts and src/styles/main.css while populating src/ with the new template files.
2026-04-02 23:12:27 +08:00
parent 2ae2ec231a
commit 7fab0c6039
56 changed files with 2268 additions and 17 deletions
@@ -0,0 +1,51 @@
+# 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.
+
+## 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