Files

T

Ryan Wang 7fab0c6039 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

1.9 KiB

Raw Blame History

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:

<!-- 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):

<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.

<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 for the full integration guide, template syntax, and configuration examples.

1.9 KiB Raw Blame History