Ryan Wang
7fab0c6039
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.
70 lines
1.9 KiB
Markdown
70 lines
1.9 KiB
Markdown
# Static Assets & Build Tooling
|
|
|
|
## Static Asset Directory
|
|
|
|
All theme static assets **must** be placed under `templates/assets/`:
|
|
|
|
```
|
|
templates/
|
|
└── assets/
|
|
├── css/
|
|
│ └── style.css
|
|
├── js/
|
|
│ └── main.js
|
|
└── images/
|
|
└── logo.png
|
|
```
|
|
|
|
---
|
|
|
|
## Referencing Static Assets in Templates
|
|
|
|
### Method 1: HTML tag attributes (recommended)
|
|
|
|
Use Thymeleaf's `@{}` expression:
|
|
|
|
```html
|
|
<!-- CSS -->
|
|
<link rel="stylesheet" th:href="@{/assets/dist/style.css}" />
|
|
|
|
<!-- JavaScript -->
|
|
<script th:src="@{/assets/dist/main.iife.js}"></script>
|
|
|
|
<!-- Image -->
|
|
<img th:src="@{/assets/images/logo.png}" alt="Logo" />
|
|
```
|
|
|
|
The path `@{/assets/dist/style.css}` maps to `templates/assets/dist/style.css` and renders as `/themes/theme-foo/assets/dist/style.css`.
|
|
|
|
**With version query string (strongly recommended — prevents caching)**:
|
|
|
|
```html
|
|
<link rel="stylesheet" th:href="@{/assets/dist/style.css?v={v}(v=${theme.spec.version})}" />
|
|
<script th:src="@{/assets/dist/main.iife.js?v={v}(v=${theme.spec.version})}"></script>
|
|
```
|
|
|
|
### Method 2: `#theme.assets()` utility
|
|
|
|
Use when you need the asset path in a non-attribute context (e.g. a JavaScript variable or inline CSS).
|
|
|
|
> Note: do **not** include `/assets/` prefix in the path argument.
|
|
|
|
```html
|
|
<script th:inline="javascript">
|
|
var logoUrl = '[(${#theme.assets("/images/logo.png")})]';
|
|
// Value: /themes/theme-foo/assets/images/logo.png
|
|
|
|
loadScript('[(${#theme.assets("/dist/main.iife.js")})]');
|
|
</script>
|
|
```
|
|
|
|
---
|
|
|
|
## Vite Integration
|
|
|
|
For themes using a modern frontend stack (TypeScript, Sass, PostCSS, TailwindCSS, etc.) or needing HTML template reuse (`include`/`slot`), the official Vite plugin is strongly recommended:
|
|
|
|
**`vite-plugin-halo-theme`**: https://github.com/halo-sigs/vite-plugin-halo-theme
|
|
|
|
See [vite-plugin.md](vite-plugin.md) for the full integration guide, template syntax, and configuration examples.
|