halo-theme-dev

Halo Theme Development

Work from the target theme and fetch current Halo documentation only when the task needs a Halo-specific contract. Do not rely on Finder signatures, template variables, or configuration fields recalled from training data.

Establish the Target

• Inspect theme.yaml, settings.yaml, the package manifest and build config, and representative templates before editing.
• Determine theme.yaml spec.requires and the actual Halo version. Do not silently raise the requirement or replace the theme's build system.
• Identify whether runtime templates are authored directly in templates/ or generated from a source directory such as src/.

Fetch Documentation on Demand

1. Start with the theme documentation index when the task involves Halo theme configuration, templates, Finder APIs, global variables, assets, annotations, i18n, packaging, or plugin integration.
2. Use the complete Halo documentation index only when the route is unclear or the task crosses documentation sections.
3. Fetch only the Markdown pages relevant to the current task. Do not load llms-full.txt by default.
4. For version-sensitive work, also read the theme API changelog, then verify exact fields and signatures against the target version or existing templates. The target version wins over current-site docs.

If online docs are unavailable, continue from the target checkout and installed dependencies when possible, and disclose what could not be verified instead of guessing.

Halo-Specific Boundaries

• Keep the theme directory name aligned with theme.yaml metadata.name.
• In a build-tool theme, edit source templates and assets, then run the existing build; do not hand-edit generated templates/ output or hashed assets.
• Read the current Thymeleaf guide before writing expressions. Halo 2.26 uses Thymeleaf 3.1, where #request, #response, #session, and #servletContext are unavailable. Do not guess expression methods or derive page URLs from request objects; use documented template variables and permalinks.
• Treat site identity and global injection as Halo-owned by default. Use site.logo, system SEO settings, Halo's head processing, and <halo:footer />; add a theme setting only for a theme-specific override with a system fallback. Check the current settings guide before adding fields to settings.yaml.
• Do not duplicate Halo-injected description or keywords. Canonical, Open Graph, Twitter Card, and structured data are optional theme/plugin capabilities and must follow the current SEO guide with conflict-avoidance switches.
• Preserve the project's established Thymeleaf layout and asset conventions. Check the relevant docs before using a Finder method, template variable, Halo utility, custom tag, or page-layout contract. When integrating official frontend widgets, follow the shared color-scheme contract in the current plugin integration guide.
• Use the starter assets below only when creating a new theme. Never replace an existing theme with a starter.

Starter Templates

The assets/ directory provides two ready-to-use theme templates:

• assets/theme-minimal/ — Zero-build-tool minimal theme with the standard route templates; ideal for quick prototyping or simple themes
• assets/theme-vite/ — Vite project template with vite-plugin-halo-theme (recommended for new themes); includes partial layout reuse and CSS toolchain

Usage: copy the directory into themes/ in your Halo working directory, ensure the folder name matches metadata.name in theme.yaml, then install and activate in Console.

Verify

Run the theme's existing build and package checks when applicable. Test every changed template type or integration path on a compatible Halo instance; at minimum cover the affected route plus one shared-layout consumer. Check rendered HTML, asset loading, pagination or empty states when relevant, and browser console errors.