From 2ed0c768a4d531cfa08534829cf727203bab8d24 Mon Sep 17 00:00:00 2001 From: Ryan Wang Date: Tue, 1 Sep 2026 16:36:38 +0800 Subject: [PATCH] Refresh Halo theme skill and starter Reworks the `halo-theme-dev` skill around current Halo theme workflows: replaces bundled reference docs with on-demand documentation guidance, broadens the skill scope, removes the OpenAI-specific agent config, and adds eval coverage for settings, SEO, and Vite layout behavior. It also updates the Vite starter by pinning `vite-plugin-halo-theme`, adding a source `layout.html` contract plus `author.html`, wiring locale-aware `lang` handling, and adding ignored/generated asset placeholders for the build output. --- .agents/skills/halo-theme-dev/SKILL.md | 128 ++++---- .../skills/halo-theme-dev/agents/openai.yaml | 4 - .../assets/theme-vite/.gitignore | 3 + .../assets/theme-vite/package.json | 2 +- .../assets/theme-vite/public/assets/.gitkeep | 0 .../assets/theme-vite/src/author.html | 16 + .../assets/theme-vite/src/layout.html | 49 +++ .../theme-vite/src/partials/layout.html | 2 +- .../assets/theme-vite/src/tags.html | 6 +- .../skills/halo-theme-dev/evals/evals.json | 42 +++ .../halo-theme-dev/references/annotations.md | 111 ------- .../halo-theme-dev/references/finder-apis.md | 53 ---- .../references/global-variables.md | 140 --------- .../references/official-plugins.md | 61 ---- .../halo-theme-dev/references/packaging.md | 39 --- .../references/static-resources.md | 69 ----- .../references/structure-and-config.md | 253 --------------- .../references/template-tags.md | 71 ----- .../halo-theme-dev/references/templates.md | 51 --- .../references/thymeleaf-tips.md | 82 ----- .../halo-theme-dev/references/vite-plugin.md | 291 ------------------ .claude/skills/halo-theme-dev | 1 + skills-lock.json | 3 +- 23 files changed, 177 insertions(+), 1300 deletions(-) delete mode 100644 .agents/skills/halo-theme-dev/agents/openai.yaml create mode 100644 .agents/skills/halo-theme-dev/assets/theme-vite/.gitignore create mode 100644 .agents/skills/halo-theme-dev/assets/theme-vite/public/assets/.gitkeep create mode 100644 .agents/skills/halo-theme-dev/assets/theme-vite/src/author.html create mode 100644 .agents/skills/halo-theme-dev/assets/theme-vite/src/layout.html create mode 100644 .agents/skills/halo-theme-dev/evals/evals.json delete mode 100644 .agents/skills/halo-theme-dev/references/annotations.md delete mode 100644 .agents/skills/halo-theme-dev/references/finder-apis.md delete mode 100644 .agents/skills/halo-theme-dev/references/global-variables.md delete mode 100644 .agents/skills/halo-theme-dev/references/official-plugins.md delete mode 100644 .agents/skills/halo-theme-dev/references/packaging.md delete mode 100644 .agents/skills/halo-theme-dev/references/static-resources.md delete mode 100644 .agents/skills/halo-theme-dev/references/structure-and-config.md delete mode 100644 .agents/skills/halo-theme-dev/references/template-tags.md delete mode 100644 .agents/skills/halo-theme-dev/references/templates.md delete mode 100644 .agents/skills/halo-theme-dev/references/thymeleaf-tips.md delete mode 100644 .agents/skills/halo-theme-dev/references/vite-plugin.md create mode 120000 .claude/skills/halo-theme-dev diff --git a/.agents/skills/halo-theme-dev/SKILL.md b/.agents/skills/halo-theme-dev/SKILL.md index 7249927..40ed551 100644 --- a/.agents/skills/halo-theme-dev/SKILL.md +++ b/.agents/skills/halo-theme-dev/SKILL.md @@ -1,91 +1,85 @@ --- name: halo-theme-dev description: > - Use when creating or modifying a Halo CMS theme: writing Thymeleaf templates, - configuring theme.yaml or settings.yaml, calling Finder APIs, using - vite-plugin-halo-theme, defining theme settings forms, referencing static assets, - implementing halo:comment or halo:footer extension points, or defining model - annotation fields (AnnotationSetting). + Create or modify Halo CMS themes, including Thymeleaf templates, theme.yaml and + settings.yaml, Finder APIs, static assets, Vite integration, theme UI providers, + page-layout integration, annotations, i18n, and error pages. Use for Halo site + theme implementation, migration, debugging, or packaging; do not use for + unrelated Thymeleaf applications or plugin-only changes. --- # Halo Theme Development -Halo is built on **Spring Boot + Spring WebFlux + Thymeleaf**. Themes use Thymeleaf templates for frontend page rendering. +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. -> **Important**: Halo's APIs, VO field names, and template variables evolve across versions. **Do not rely on training data for specific field names, method signatures, or type structures.** When writing code that accesses template variables or calls Finder API methods, always fetch the relevant online doc from the References section below first. +## Establish the Target -## Thymeleaf Quick Reference +- 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/`. -Full docs: https://raw.githubusercontent.com/thymeleaf/thymeleaf-docs/refs/heads/master/docs/tutorials/3.1/usingthymeleaf.md +## Fetch Documentation on Demand -Core syntax cheatsheet: +1. Start with the [theme documentation index](https://docs.halo.run/developer-guide/theme/index.md) + 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](https://docs.halo.run/llms.txt) + 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](https://docs.halo.run/developer-guide/theme/api-changelog.md), + then verify exact fields and signatures against the target version or existing + templates. The target version wins over current-site docs. -```html - -

+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 - -Post link - - - -
  • - - -
    Next page
    -
    Last page
    - - -
    ...
    - - -
    - - - - - - - - -``` - -## Development Workflow - -1. Create a theme folder under `themes/` in the Halo working directory (must match `metadata.name` in `theme.yaml`) -2. Write `theme.yaml` (required) and `settings.yaml` (optional) -3. Create template files under `templates/` -4. Install and activate the theme in Console → Theme Management -5. Visit the frontend to verify - -Disable Thymeleaf caching during development: set env var `SPRING_THYMELEAF_CACHE=false` (Docker), or `spring.thymeleaf.cache: false` in config (source mode). +- 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](https://docs.halo.run/developer-guide/theme/thymeleaf.md) + 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 ``; + add a theme setting only for a theme-specific override with a system fallback. + Check the current [settings guide](https://docs.halo.run/developer-guide/theme/settings.md) + 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](https://docs.halo.run/developer-guide/theme/seo.md) + 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](https://docs.halo.run/developer-guide/theme/plugin-integration.md). +- 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 all 8 template files; ideal for quick prototyping or simple themes +- **`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. -## References Index +## Verify -| File | Content | When to read | -| ---- | ------- | ------------ | -| [references/structure-and-config.md](references/structure-and-config.md) | Directory structure, theme.yaml fields, settings.yaml form definition | Creating a theme, configuring theme.yaml/settings.yaml | -| [references/vite-plugin.md](references/vite-plugin.md) | vite-plugin-halo-theme integration guide, include/slot template syntax, TailwindCSS integration | Setting up a Vite-based theme (recommended) | -| [references/templates.md](references/templates.md) | Template route mapping, available variables per template | Writing template files | -| [references/global-variables.md](references/global-variables.md) | Global variables (site, theme, theme.config) and type definitions | Accessing site info or theme setting values | -| [references/finder-apis.md](references/finder-apis.md) | All Finder APIs (postFinder, categoryFinder, tagFinder, menuFinder, singlePageFinder, etc.) | Querying data from any template | -| [references/static-resources.md](references/static-resources.md) | Static asset reference methods (`@{}`, `#theme.assets()`) | Referencing CSS/JS/images in plain HTML themes | -| [references/template-tags.md](references/template-tags.md) | Custom tags (halo:comment extension point, halo:footer injection) | Integrating comment plugins, injecting footer code | -| [references/official-plugins.md](references/official-plugins.md) | Official plugin integration: pluginFinder.available(), search widget, dark mode color scheme adaptation | Adding search, adapting dark mode for plugin UI | -| [references/annotations.md](references/annotations.md) | AnnotationSetting for model custom fields, `#annotations` utility for reading metadata in templates | Adding custom fields to menu items/posts/categories and using them in templates | -| [references/packaging.md](references/packaging.md) | Packaging a theme as a ZIP using `@halo-dev/theme-package-cli` | Preparing a theme for release or upload | -| [references/thymeleaf-tips.md](references/thymeleaf-tips.md) | Halo-specific Thymeleaf best practices: literal substitutions, safe navigation, meta tag rules, permalink syntax | Writing any template file | +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. diff --git a/.agents/skills/halo-theme-dev/agents/openai.yaml b/.agents/skills/halo-theme-dev/agents/openai.yaml deleted file mode 100644 index c18da1f..0000000 --- a/.agents/skills/halo-theme-dev/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Halo Theme Development" - short_description: "Build Halo CMS themes with Thymeleaf" - default_prompt: "Help me create a Halo theme" diff --git a/.agents/skills/halo-theme-dev/assets/theme-vite/.gitignore b/.agents/skills/halo-theme-dev/assets/theme-vite/.gitignore new file mode 100644 index 0000000..097ab26 --- /dev/null +++ b/.agents/skills/halo-theme-dev/assets/theme-vite/.gitignore @@ -0,0 +1,3 @@ +node_modules/ +templates +dist \ No newline at end of file diff --git a/.agents/skills/halo-theme-dev/assets/theme-vite/package.json b/.agents/skills/halo-theme-dev/assets/theme-vite/package.json index aa15993..6a9af15 100644 --- a/.agents/skills/halo-theme-dev/assets/theme-vite/package.json +++ b/.agents/skills/halo-theme-dev/assets/theme-vite/package.json @@ -7,7 +7,7 @@ }, "devDependencies": { "@halo-dev/theme-package-cli": "^1.0.1", - "@halo-dev/vite-plugin-halo-theme": "latest", + "@halo-dev/vite-plugin-halo-theme": "1.0.3", "vite": "^8.0.0" }, "packageManager": "pnpm@10.33.0" diff --git a/.agents/skills/halo-theme-dev/assets/theme-vite/public/assets/.gitkeep b/.agents/skills/halo-theme-dev/assets/theme-vite/public/assets/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.agents/skills/halo-theme-dev/assets/theme-vite/src/author.html b/.agents/skills/halo-theme-dev/assets/theme-vite/src/author.html new file mode 100644 index 0000000..fffb851 --- /dev/null +++ b/.agents/skills/halo-theme-dev/assets/theme-vite/src/author.html @@ -0,0 +1,16 @@ + + + +
    +

    +

    + +
      + +
    + + +
    +     diff --git a/.agents/skills/halo-theme-dev/assets/theme-vite/src/layout.html b/.agents/skills/halo-theme-dev/assets/theme-vite/src/layout.html new file mode 100644 index 0000000..693034b --- /dev/null +++ b/.agents/skills/halo-theme-dev/assets/theme-vite/src/layout.html @@ -0,0 +1,49 @@ + + + + + + Site Title + + + + + + + +
    +
    + Site Title + +
    +
    + +
    +
    + +
    +
    + +
    +
    +

    + +
    +
    + + diff --git a/.agents/skills/halo-theme-dev/assets/theme-vite/src/partials/layout.html b/.agents/skills/halo-theme-dev/assets/theme-vite/src/partials/layout.html index 998e5de..4e2918d 100644 --- a/.agents/skills/halo-theme-dev/assets/theme-vite/src/partials/layout.html +++ b/.agents/skills/halo-theme-dev/assets/theme-vite/src/partials/layout.html @@ -1,5 +1,5 @@ - + diff --git a/.agents/skills/halo-theme-dev/assets/theme-vite/src/tags.html b/.agents/skills/halo-theme-dev/assets/theme-vite/src/tags.html index 75751f7..2f41d5d 100644 --- a/.agents/skills/halo-theme-dev/assets/theme-vite/src/tags.html +++ b/.agents/skills/halo-theme-dev/assets/theme-vite/src/tags.html @@ -6,11 +6,7 @@

    Tags

    • - +
    diff --git a/.agents/skills/halo-theme-dev/evals/evals.json b/.agents/skills/halo-theme-dev/evals/evals.json new file mode 100644 index 0000000..5e77bb8 --- /dev/null +++ b/.agents/skills/halo-theme-dev/evals/evals.json @@ -0,0 +1,42 @@ +{ + "skill_name": "halo-theme-dev", + "evals": [ + { + "id": 1, + "prompt": "Create a corporate website theme for Halo 2.26. The theme needs settings for its color scheme, homepage sections, and footer styling. The requester also wants site logo, favicon, global head code, and footer code fields in the theme settings. Build the smallest runnable theme and explain which settings belong to Halo instead of the theme.", + "expected_output": "A runnable theme that reuses Halo's system-managed site identity and code injection while defining settings only for theme-specific appearance and layout.", + "files": [], + "expectations": [ + "settings.yaml does not duplicate the site logo, favicon, or general head and footer code injection", + "Templates use system variables such as site.logo and site.favicon and preserve halo:footer", + "The theme directory name, theme.yaml metadata.name, and minimum Halo version are consistent", + "Theme settings contain only theme-specific color, layout, and component options" + ] + }, + { + "id": 2, + "prompt": "Add canonical, Open Graph, and Article JSON-LD metadata to post.html in a Halo 2.26 theme. The page needs the current post's absolute URL. The current draft uses #request.getRequestURI() and builds JSON with string concatenation. Correct it and provide the template.", + "expected_output": "SEO metadata generated from Halo page variables and safe Thymeleaf JavaScript inlining without Servlet request objects or manual JSON escaping.", + "files": [], + "expectations": [ + "The template does not use #request, #response, #session, #servletContext, or #ctx.exchange", + "The post URL is built from documented variables such as site.url and post.status.permalink", + "JSON-LD uses th:inline=javascript serialization instead of manually concatenating quoted strings", + "The template does not duplicate Halo-injected description or keywords and allows optional SEO output to be disabled" + ] + }, + { + "id": 3, + "prompt": "Modify an existing vite-plugin-halo-theme project whose source files live in src/ and whose templates/ directory and hashed assets are generated by the build. Add the layout.html html(head, content) contract for plugin-rendered frontend pages and ensure every page has the correct lang and title.", + "expected_output": "Only source templates are edited, existing build tooling generates the runtime output, the layout contract produces one title, and the language follows the current locale.", + "files": [], + "expectations": [ + "Only source templates under src are edited; generated templates, hashed assets, and lockfiles are not hand-edited", + "layout.html declares html(head, content) and preserves halo:footer", + "A non-null head does not produce both a default title and a caller-provided title", + "The html lang value follows the current locale instead of being fixed to en", + "The project's existing build or verification command is run after the change" + ] + } + ] +} diff --git a/.agents/skills/halo-theme-dev/references/annotations.md b/.agents/skills/halo-theme-dev/references/annotations.md deleted file mode 100644 index 261c84f..0000000 --- a/.agents/skills/halo-theme-dev/references/annotations.md +++ /dev/null @@ -1,111 +0,0 @@ -# Model Metadata (Annotations) - -Themes can extend built-in Halo models with custom fields via `AnnotationSetting` resources (e.g. adding an icon to menu items, or a download URL to posts), then read those values in templates via the `#annotations` utility. - -## Defining a Metadata Form (AnnotationSetting) - -Create a file (any name) in the theme root, e.g. `annotation-setting.yaml`, and declare an `AnnotationSetting` resource: - -```yaml -apiVersion: v1alpha1 -kind: AnnotationSetting -metadata: - name: theme-foo-menuitem-abc123 # recommended: add theme prefix + random suffix to avoid conflicts -spec: - targetRef: - group: "" - kind: MenuItem - formSchema: - - $formkit: text - name: icon - label: Menu icon class - value: "" -``` - -Multiple models can be declared in the same file separated by `---`: - -```yaml -apiVersion: v1alpha1 -kind: AnnotationSetting -metadata: - name: theme-foo-post-abc123 -spec: - targetRef: - group: content.halo.run - kind: Post - formSchema: - - $formkit: text - name: download_url - label: Download URL - value: "" - ---- -apiVersion: v1alpha1 -kind: AnnotationSetting -metadata: - name: theme-foo-menuitem-abc123 -spec: - targetRef: - group: "" - kind: MenuItem - formSchema: - - $formkit: text - name: icon - label: Icon - value: "" -``` - -### Supported Models - -| Model | `group` | `kind` | -| ----- | ------- | ------ | -| Post | `content.halo.run` | `Post` | -| Single page | `content.halo.run` | `SinglePage` | -| Post category | `content.halo.run` | `Category` | -| Post tag | `content.halo.run` | `Tag` | -| Menu item | `""` | `MenuItem` | -| User | `""` | `User` | - -### Notes - -- All values in `metadata.annotations` are **strings**, so form values must also be strings. -- Do not use components with non-string output such as `number`, `group`, or `repeater`. -- For `checkbox`, explicitly set `on-value` / `off-value` to string values (e.g. `"true"` / `"false"`). -- Use a theme-name prefix plus a random suffix for `metadata.name` to avoid conflicts with other themes/plugins, e.g. `theme-earth-post-wanfs5`. - -## Reading Metadata in Templates - -Halo provides a `#annotations` utility object in Thymeleaf with three methods: - -### `#annotations.get(object, key)` — Get a value - -```html -
    -
  • - - -
    • -
    -``` - -### `#annotations.getOrDefault(object, key, defaultValue)` — Get a value with fallback - -```html - -``` - -### `#annotations.contains(object, key)` — Check if a key exists - -```html - -``` - -## Online Docs - -> **`AnnotationSetting` spec and supported models may change across Halo versions. Fetch the relevant doc if unsure about supported `group`/`kind` combinations or form schema constraints.** - -- Using metadata in templates: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/annotations.md -- Defining annotation forms: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/annotations-form.md diff --git a/.agents/skills/halo-theme-dev/references/finder-apis.md b/.agents/skills/halo-theme-dev/references/finder-apis.md deleted file mode 100644 index bf7b2a6..0000000 --- a/.agents/skills/halo-theme-dev/references/finder-apis.md +++ /dev/null @@ -1,53 +0,0 @@ -# Finder API - -Finder APIs query data from **any template location** regardless of the current route — ideal for sidebars, footers, and other global data needs. - -## Available Finders - -| Finder | Purpose | -| ------ | ------- | -| `postFinder` | Post list / detail / prev-next / archives | -| `categoryFinder` | Category list / tree structure / breadcrumbs | -| `tagFinder` | Tag list / detail | -| `menuFinder` | Menus and menu items | -| `singlePageFinder` | Single page list / detail | -| `commentFinder` | Comments and replies | -| `contributorFinder` | Contributors | -| `siteStatsFinder` | Site statistics | -| `themeFinder` | Theme information | -| `pluginFinder` | Plugin information | - -## Key Usage Pattern - -Use `th:with` to bind the result in the current scope: - -```html -
    - -
    -``` - -## Common Notes - -- `postFinder.list({...})` is the recommended unified query method (all parameters are optional); it supersedes the deprecated `list(page, size)`, `listByCategory(...)`, etc. -- `metadata.name` is the unique resource identifier — it is not the display name (`displayName`/`title`). -- Pair `settings.yaml` `categorySelect`/`tagSelect` inputs with Finder queries so users can configure query parameters in Console instead of hard-coding them in templates. - -## Online Docs - -> **Do not rely on training data for Finder API method signatures — Halo evolves across versions and your training data may be outdated or incomplete. Always fetch the relevant doc before writing code that calls a specific Finder method.** - -- postFinder: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/finder-apis/post.md -- categoryFinder: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/finder-apis/category.md -- tagFinder: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/finder-apis/tag.md -- menuFinder: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/finder-apis/menu.md -- singlePageFinder: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/finder-apis/single-page.md -- commentFinder: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/finder-apis/comment.md -- contributorFinder: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/finder-apis/contributor.md -- siteStatsFinder: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/finder-apis/site-stats.md -- themeFinder: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/finder-apis/theme.md -- pluginFinder: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/plugin/api-reference/server/finder-for-theme.md diff --git a/.agents/skills/halo-theme-dev/references/global-variables.md b/.agents/skills/halo-theme-dev/references/global-variables.md deleted file mode 100644 index 155700f..0000000 --- a/.agents/skills/halo-theme-dev/references/global-variables.md +++ /dev/null @@ -1,140 +0,0 @@ -# Global Variables - -The following variables are available in all templates without any additional declaration. - ---- - -## `site` — Site information - -Source: Console → System Settings. - -```json -{ - "title": "Site Title", - "subtitle": "Site Subtitle", - "url": "https://example.com", - "logo": "https://example.com/logo.png", - "favicon": "https://example.com/favicon.ico", - "allowRegistration": false, - "post": { - "postPageSize": 10, - "archivePageSize": 10, - "categoryPageSize": 10, - "tagPageSize": 10 - }, - "seo": { - "blockSpiders": false, - "keywords": "keywords", - "description": "Site description" - }, - "comment": { - "enable": true, - "systemUserOnly": false, - "requireReviewForNew": false - }, - "routes": { - "categoriesUri": "/categories", - "tagsUri": "/tags", - "archivesUri": "/archives" - } -} -``` - -**Common examples**: - -```html - -Logo - -``` - ---- - -## `theme` — Current theme info - -```json -{ - "metadata": { - "name": "theme-foo", - "creationTimestamp": "..." - }, - "spec": { - "displayName": "My Theme", - "version": "1.0.0", - "author": { "name": "Author", "website": "https://example.com" }, - "description": "Theme description", - "logo": "https://example.com/logo.png", - "homepage": "https://github.com/example/theme-foo", - "settingName": "theme-foo-setting", - "configMapName": "theme-foo-configMap" - }, - "config": { - "style": { "color_scheme": "system" }, - "layout": { "nav": "single" } - } -} -``` - -**Common examples**: - -```html - - - - - - -``` - ---- - -## `theme.config` — Theme settings values - -Access pattern: `theme.config.[group].[name]` - -- `group`: value of `spec.forms[].group` in `settings.yaml` -- `name`: value of `spec.forms[].formSchema[].name` - -**Example** (based on the settings.yaml in [structure-and-config.md](structure-and-config.md)): - -```html - - - - -``` - ---- - -## `#theme.assets()` — Static asset path utility - -Returns the full path to a static asset for use in non-attribute contexts (e.g. inside JavaScript). - -> Note: the path passed to this function does **not** need an `/assets/` prefix. - -```html - -``` - ---- - -## Online Docs - -> **If you need the exact structure of `site`, `theme`, or `theme.config`, fetch the doc below — do not guess field names from training data.** - -https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/theme/global-variables.md - ---- - -## `haloCommentEnabled` — Comment component status - -Boolean. Evaluates both "is a comment plugin installed" and "are comments enabled for this page". Use together with the `halo:comment` custom tag: - -```html -
    - -
    -``` diff --git a/.agents/skills/halo-theme-dev/references/official-plugins.md b/.agents/skills/halo-theme-dev/references/official-plugins.md deleted file mode 100644 index 389ae6d..0000000 --- a/.agents/skills/halo-theme-dev/references/official-plugins.md +++ /dev/null @@ -1,61 +0,0 @@ -# Official Plugin Integration - -Halo's official plugins can extend the frontend UI. Themes should adapt to these plugins rather than re-implementing the same functionality. - -## Checking Plugin Availability - -Use `pluginFinder.available(pluginName)` to conditionally render plugin-dependent UI. This prevents broken UI when the plugin is not installed. - -```html - -``` - -Always guard plugin-dependent elements with `th:if="${pluginFinder.available('...')}"`. - -## Search Widget (PluginSearchWidget) - -The official search plugin provides a ready-made search UI. Themes do not need to build their own search — just add a trigger button: - -```html - -``` - -## Dark Mode Adaptation - -Official plugins that provide UI components (search widget, comment component, etc.) support a shared color scheme system. Themes that implement dark mode should apply the appropriate class or `data-color-scheme` attribute to `` or `` so plugin UI matches the theme's color scheme automatically. - -### Method 1: CSS class on `` or `` - -| Class | Effect | -| ----- | ------ | -| `color-scheme-auto` | Follows system dark/light preference | -| `color-scheme-dark` or `dark` | Force dark mode | -| `color-scheme-light` or `light` | Force light mode | - -```html - - - - - -``` - -### Method 2: `data-color-scheme` attribute on `` or `` - -| Value | Effect | -| ----- | ------ | -| `auto` | Follows system preference | -| `dark` | Force dark mode | -| `light` | Force light mode | - -```html - -``` - -> Both methods achieve the same result. Dark mode switching is typically handled by frontend JavaScript (toggling the class/attribute at runtime). This applies to all official plugins that render UI (search widget, comment component, etc.). diff --git a/.agents/skills/halo-theme-dev/references/packaging.md b/.agents/skills/halo-theme-dev/references/packaging.md deleted file mode 100644 index b8f7ccb..0000000 --- a/.agents/skills/halo-theme-dev/references/packaging.md +++ /dev/null @@ -1,39 +0,0 @@ -# Theme Packaging - -Use [`@halo-dev/theme-package-cli`](https://github.com/halo-dev/theme-package-cli) to package a theme into a ZIP file for uploading to Halo Console or distributing to others. - -## Installation - -```bash -npm install -g @halo-dev/theme-package-cli -``` - -Or run without installing via `npx`: - -```bash -npx @halo-dev/theme-package-cli -``` - -## Usage - -Run in the theme root directory (the one containing `theme.yaml`): - -```bash -# Package only essential files (recommended) -theme-package - -# Package all files (excluding node_modules, dist, .git, etc.) -theme-package --all -``` - -## Default Package Contents (without `--all`) - -| Included | Description | -| -------- | ----------- | -| `templates/` | Templates and static assets | -| `*.yaml` / `*.yml` | Config files: `theme.yaml`, `settings.yaml`, etc. | -| `i18n/` | Internationalization files (if present) | -| `README.md` | Documentation file (if present) | -| `LICENSE` | License file (if present) | - -> For Vite-based themes, run `npm run build` first to generate the `templates/` output, then run the packaging command. diff --git a/.agents/skills/halo-theme-dev/references/static-resources.md b/.agents/skills/halo-theme-dev/references/static-resources.md deleted file mode 100644 index a91107b..0000000 --- a/.agents/skills/halo-theme-dev/references/static-resources.md +++ /dev/null @@ -1,69 +0,0 @@ -# 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 - - - - - - - -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 - - -``` - -### 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 - -``` - ---- - -## 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. diff --git a/.agents/skills/halo-theme-dev/references/structure-and-config.md b/.agents/skills/halo-theme-dev/references/structure-and-config.md deleted file mode 100644 index 62dfe9b..0000000 --- a/.agents/skills/halo-theme-dev/references/structure-and-config.md +++ /dev/null @@ -1,253 +0,0 @@ -# Directory Structure & Configuration - -## Directory Structure - -``` -my-theme/ -├── templates/ -│ ├── assets/ # Static assets (CSS/JS/images etc.) — must be placed here -│ │ ├── css/ -│ │ │ └── style.css -│ │ └── js/ -│ │ └── main.js -│ ├── index.html # Home page -│ ├── post.html # Post detail -│ ├── page.html # Single page detail -│ ├── archives.html # Post archives -│ ├── tags.html # Tag listing -│ ├── tag.html # Tag archive -│ ├── categories.html # Category listing -│ └── category.html # Category archive -├── theme.yaml # Theme configuration (required) -└── settings.yaml # Theme settings form definition (optional) -``` - -> **Important**: The theme folder name must match the `metadata.name` field in `theme.yaml`; otherwise some assets may fail to load. - -## theme.yaml - -The theme root directory must contain `theme.yaml`. Minimal runnable config: - -```yaml -apiVersion: theme.halo.run/v1alpha1 -kind: Theme -metadata: - name: theme-foo # must match the theme folder name -spec: - displayName: My Theme - version: 1.0.0 - requires: ">=2.0.0" -``` - -Full field example: - -```yaml -apiVersion: theme.halo.run/v1alpha1 -kind: Theme -metadata: - name: theme-foo -spec: - displayName: My Theme - author: - name: Author Name - website: https://example.com - description: An example theme - logo: https://example.com/logo.png - homepage: https://github.com/example/theme-foo - repo: https://github.com/example/theme-foo.git - issues: https://github.com/example/theme-foo/issues - settingName: "theme-foo-setting" # must match metadata.name in settings.yaml - configMapName: "theme-foo-configMap" - customTemplates: # optional - post: - - name: Documentation - description: Article in documentation format - screenshot: - file: post_documentation.html - category: - - name: Knowledge Base - description: Knowledge base category - screenshot: - file: category_knowledge.html - page: - - name: About - description: About page - screenshot: - file: page_about.html - version: 1.0.0 - requires: ">=2.0.0" - license: - - name: "GPL-3.0" - url: "https://github.com/example/theme-foo/blob/main/LICENSE" -``` - -### Key Fields - -| Field | Description | Required | -| ----- | ----------- | -------- | -| `metadata.name` | Unique theme identifier — **must match the folder name** | Yes | -| `spec.displayName` | Display name | Yes | -| `spec.version` | Theme version | Yes | -| `spec.requires` | Minimum required Halo version | Yes | -| `spec.settingName` | Setting resource name — must match `metadata.name` in settings.yaml | No | -| `spec.configMapName` | ConfigMap name for persisting settings | No (configure together with settingName) | -| `spec.customTemplates` | Custom template configuration | No | - -> After modifying `theme.yaml`, click "Reload Theme Configuration" on the theme page in Console for changes to take effect. - -## settings.yaml - -Defines a form that is auto-rendered on the theme settings page in Console, using [FormKit](https://github.com/formkit/formkit). - -```yaml -apiVersion: v1alpha1 -kind: Setting -metadata: - name: theme-foo-setting # must match spec.settingName in theme.yaml -spec: - forms: - - group: style # group name (accessed in templates as theme.config.style.xxx) - label: Style - formSchema: - - $formkit: radio - name: color_scheme # field name (accessed as theme.config.style.color_scheme) - label: Default color scheme - value: system - options: - - label: Follow system - value: system - - label: Dark - value: dark - - label: Light - value: light - - $formkit: color - name: background_color - label: Background color - value: "#f2f2f2" - - group: layout - label: Layout - formSchema: - - $formkit: radio - name: nav - label: Navigation layout - value: "single" - options: - - label: Single column - value: "single" - - label: Double column - value: "double" -``` - -### Using Settings Values in Templates - -Pattern: `theme.config.[group].[name]` - -```html - - -
      - Single-column nav -
    -
    Double-column nav
    - -``` - -### Native FormKit Input Types - -Commonly used native input components in theme settings (see links for full docs): - -| `$formkit` value | Purpose | Docs | -| ---------------- | ------- | ---- | -| `text` | Single-line text | https://formkit.com/inputs/text.md | -| `textarea` | Multi-line text | https://formkit.com/inputs/textarea.md | -| `number` | Number input | https://formkit.com/inputs/number.md | -| `password` | Password input | https://formkit.com/inputs/password.md | -| `radio` | Radio buttons (options list) | https://formkit.com/inputs/radio.md | -| `checkbox` | Checkbox (single or multi-select) | https://formkit.com/inputs/checkbox.md | -| `color` | Color picker (returns hex value) | https://formkit.com/inputs/color.md | -| `range` | Slider range | https://formkit.com/inputs/range.md | -| `date` | Date picker | https://formkit.com/inputs/date.md | -| `datetime-local` | Date-time picker | https://formkit.com/inputs/datetime-local.md | -| `button` | Button | https://formkit.com/inputs/button.md | -| `email` | Email input | https://formkit.com/inputs/email.md | -| `group` | Group (for grouping fields) | https://formkit.com/inputs/group.md | -| `url` | URL input | https://formkit.com/inputs/url.md | - -FormKit Inputs overview: https://formkit.com/inputs - -FormKit Schema (conditional rendering, loops, expressions, advanced usage): https://formkit.com/essentials/schema.md - -> Note: FormKit Pro input components are not supported. - -### Halo Extended Input Types - -Additional input components provided by Halo on top of FormKit: - -| `$formkit` value | Purpose | -| ---------------- | ------- | -| `select` | Enhanced dropdown with multi-select, search, and remote data source | -| `switch` | Toggle switch (boolean or custom on/off values) | -| `toggle` | Visual toggle supporting image/color/text options | -| `attachment` | Attachment picker (preview, direct upload, select from library) | -| `attachmentInput` | Attachment picker (library popup only) | -| `code` | Code editor (supports yaml/html/js/css/json) | -| `array` | Object array (add/remove/reorder — recommended over repeater) | -| `list` | Primitive array (strings, numbers, etc.) | -| `categorySelect` | Post category selector (returns `metadata.name`) | -| `categoryCheckbox` | Post category checkbox (returns array of `metadata.name`) | -| `tagSelect` | Post tag selector (returns `metadata.name`) | -| `tagCheckbox` | Post tag checkbox (returns array of `metadata.name`) | -| `postSelect` | Post selector | -| `singlePageSelect` | Single page selector | -| `menuSelect` | Menu selector (supports multi-select) | -| `menuCheckbox` | Menu checkbox | -| `menuRadio` | Menu radio | -| `iconify` | Icon picker (Iconify-based, supports svg/dataurl/url/name formats) | -| `secret` | Secret resource selector | -| `verificationForm` | Remote verification form group | - -Full parameter reference: https://raw.githubusercontent.com/halo-dev/docs/refs/heads/main/docs/developer-guide/form-schema.md - -### FormKit Schema Gotchas - -**1. Inside `array` / `list` children, use `$value` — not `$get()`** - -Within the `children` of an `array`, `list`, or `repeater`, access the current item's data via `$value`, not `$get(id).value`. `$get()` can only reference standalone named input nodes by `id`; it cannot reach the current item in a nested context. - -```yaml -# ✅ Correct: use $value.[name] to reference a sibling field -- $formkit: array - name: socials - children: - - $formkit: text - name: platform - label: Platform - - $formkit: text - name: url - label: URL - if: "$value.platform !== ''" # references sibling field "platform" - - # ❌ Wrong: $get(platform).value does not work in a nested context - - $formkit: text - name: url - if: "$get(platform).value !== ''" -``` - -**2. Nodes using `if` must also declare a `key`** - -Any `$formkit`/`$el`/`$cmp` node with an `if` attribute must declare a unique `key`. Without it, Vue reuses DOM nodes when the condition toggles, causing stale form values or rendering glitches. - -```yaml -# ✅ Correct: add key whenever if is present -- $formkit: text - key: url-field - name: url - label: URL - if: "$value.show_link === true" - -# ❌ Wrong: missing key may cause value leakage on toggle -- $formkit: text - name: url - label: URL - if: "$value.show_link === true" -``` diff --git a/.agents/skills/halo-theme-dev/references/template-tags.md b/.agents/skills/halo-theme-dev/references/template-tags.md deleted file mode 100644 index e314b5c..0000000 --- a/.agents/skills/halo-theme-dev/references/template-tags.md +++ /dev/null @@ -1,71 +0,0 @@ -# Custom Template Tags - -Halo provides proprietary custom tags for code injection and extension points. - ---- - -## `` — Comment extension point - -### Description - -Extension point tag for the comment component. When a plugin (such as the official comment plugin) implements this extension point, it renders the comment component at this tag's location. - -### Usage - -```html title="templates/post.html" - -
    - -
    -``` - -```html title="templates/page.html" -
    - -
    -``` - -### Attributes - -| Attribute | Description | -| --------- | ----------- | -| `group` | Resource group | -| `kind` | Resource type | -| `name` | Unique resource identifier (`metadata.name`) | - -### Supported Resource Types - -| Resource | `group` | `kind` | -| -------- | ------- | ------ | -| Post | `content.halo.run` | `Post` | -| Single page | `content.halo.run` | `SinglePage` | - ---- - -## `` — Footer code injection - -### Description - -Renders the "Footer Code" configured in Console → System Settings → Code Injection at this tag's location. All themes should include this tag in the footer to ensure full Halo functionality (e.g. analytics scripts injected by plugins). - -### Usage - -```html title="templates/index.html (bottom of any template)" - - - -
    - -

    © 2024 My Site

    - - - -
    - -``` - -> For complete Halo functionality, include this tag in every template that contains a `` element. diff --git a/.agents/skills/halo-theme-dev/references/templates.md b/.agents/skills/halo-theme-dev/references/templates.md deleted file mode 100644 index c9c7d4e..0000000 --- a/.agents/skills/halo-theme-dev/references/templates.md +++ /dev/null @@ -1,51 +0,0 @@ -# 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 diff --git a/.agents/skills/halo-theme-dev/references/thymeleaf-tips.md b/.agents/skills/halo-theme-dev/references/thymeleaf-tips.md deleted file mode 100644 index 5325cd8..0000000 --- a/.agents/skills/halo-theme-dev/references/thymeleaf-tips.md +++ /dev/null @@ -1,82 +0,0 @@ -# Thymeleaf Best Practices for Halo Themes - -**1. Prefer literal substitutions over string concatenation** - -```html - - - - - -``` - -**2. Use safe navigation `?.` to avoid NullPointerException** - -```html - - -``` - -**3. Use Elvis operator `?:` for default values** - -```html -

    -``` - -**4. Use `th:block` to group without adding extra DOM elements** - -```html - -

    -
      ...
    -     -``` - -**5. Use `th:classappend` for conditional classes** - -```html - -... - - -... -``` - -**6. Use `#lists.isEmpty()` and `#strings.isEmpty()` for null-safe checks** - -```html -
    - -
    -``` - -**7. Do not manually add meta tags — Halo injects them automatically** - -Only `` needs to be in the theme. Halo automatically injects at runtime: -- `<meta name="description">` and `<meta name="keywords">` -- Open Graph tags (`og:title`, `og:description`, `og:image`, etc.) -- Twitter Card tags and canonical URL - -```html -<!-- ✅ correct --> -<head> - <title th:text="${site.title}">Site Title - - - - - Site Title - - - -``` - -**8. Use `@{${url}}` for dynamic permalink URLs** - -```html - -... - - -... -``` diff --git a/.agents/skills/halo-theme-dev/references/vite-plugin.md b/.agents/skills/halo-theme-dev/references/vite-plugin.md deleted file mode 100644 index ac22c90..0000000 --- a/.agents/skills/halo-theme-dev/references/vite-plugin.md +++ /dev/null @@ -1,291 +0,0 @@ -# Vite Integration (Recommended) - -> **Strongly recommended** for building theme projects. Compared to plain Thymeleaf, this approach provides a modern frontend development experience (TypeScript, Sass, PostCSS, TailwindCSS) plus lightweight HTML component reuse (`include`/`slot`) — significantly reducing the verbosity of Thymeleaf's native fragment system. - ---- - -## vite-plugin-halo-theme - -- GitHub: https://github.com/halo-sigs/vite-plugin-halo-theme -- NPM: `@halo-dev/vite-plugin-halo-theme` - -### Key Features - -1. **HTML template reuse**: supports ``, `` (default and named), and `` syntax, preprocessed at Vite build time — fully independent of Thymeleaf. -2. **Automatic multi-page entry scanning**: automatically discovers all `.html` files under `src/` (except `src/partials/`) as Vite build entries, with output going to `templates/`. -3. **Static asset handling**: CSS/JS in `src/` is bundled by Vite into `templates/assets/`; files in `public/` are copied directly to `templates/assets/` without processing. - ---- - -## Directory Convention - -``` -my-theme/ -├── src/ -│ ├── css/ -│ │ └── main.css # CSS source -│ ├── js/ -│ │ └── main.ts # TypeScript source -│ ├── partials/ # Not treated as page entries; referenced via include -│ │ ├── layout.html # Shared layout -│ │ └── post-card.html # Reusable post card component -│ ├── index.html # Home page entry → templates/index.html -│ ├── post.html # → templates/post.html -│ ├── page.html -│ ├── archives.html -│ ├── tags.html -│ ├── tag.html -│ ├── categories.html -│ └── category.html -├── public/ # Copied directly to templates/assets/ (no Vite processing) -├── templates/ # Build output directory (add to .gitignore) -├── vite.config.ts -├── package.json -├── .gitignore -├── theme.yaml -└── settings.yaml -``` - ---- - -## Quick Setup - -### package.json - -```json -{ - "type": "module", - "scripts": { - "dev": "vite build --watch", - "build": "vite build" - }, - "devDependencies": { - "@halo-dev/vite-plugin-halo-theme": "latest", - "vite": "^6.0.0" - } -} -``` - -### vite.config.ts - -```ts -import { defineConfig } from "vite"; -import { haloThemePlugin } from "@halo-dev/vite-plugin-halo-theme"; - -export default defineConfig({ - plugins: [haloThemePlugin()], -}); -``` - -### .gitignore - -```gitignore -node_modules/ -templates/ -!templates/.gitkeep -``` - ---- - -## Template Syntax (build-time only — independent of Thymeleaf) - -> **Important**: `include`/`slot` syntax is processed at **Vite build time**; Thymeleaf syntax is processed at **server runtime**. The two systems are fully isolated and can be mixed freely. - -### `` — Import a partial - -```html - -
    Page content
    -     -``` - -### Named Slots - -Declare slots in a partial (`src/partials/layout.html`): - -```html - - - Default title - - - - - -``` - -Use in a page: - -```html - - -
    -     -``` - -### Include Path Resolution - -| Syntax | Resolves to | -| ------ | ----------- | -| `foo.html` | `src/partials/foo.html` (preferred) | -| `partials/foo.html` | `src/partials/foo.html` | -| `./foo.html` | Relative to current file | -| `/foo.html` | Relative to `src/` root | - -### Static Asset Paths - -**All HTML files — both `src/*.html` and `src/partials/*.html` — resolve static asset references relative to `src/`**, regardless of the file's actual location. - -```html - - - - - - -``` - -Always write asset paths as if the file is in `src/`, even when it is inside `src/partials/`. - ---- - -## Full Example: Shared Layout - -### `src/partials/layout.html` - -```html - - - - - - - Site title - - - - -
    - - -
    - -
    - -
    - -
    - -
    - - -``` - -### `src/index.html` - -```html - - - -
    -
      -
    • - - -

      -
      • -
    - -
    -     -``` - -### `src/post.html` - -```html - - - - - -``` - ---- - -## TailwindCSS Integration - -```bash -pnpm add -D tailwindcss @tailwindcss/vite -``` - -```ts -// vite.config.ts -import tailwindcss from "@tailwindcss/vite"; -import { haloThemePlugin } from "@halo-dev/vite-plugin-halo-theme"; -import { defineConfig } from "vite"; - -export default defineConfig({ - plugins: [tailwindcss(), haloThemePlugin()], -}); -``` - -```css -/* src/css/main.css */ -@import "tailwindcss"; -``` - ---- - -## Ready-to-use Templates - -The skill's `assets/` directory provides two ready-to-use templates: - -- `assets/theme-minimal/` — Zero-build-tool minimal theme; good for quick prototyping or plain HTML/CSS themes -- `assets/theme-vite/` — Full Vite project with vite-plugin-halo-theme; recommended as the starting point for new themes - -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. diff --git a/.claude/skills/halo-theme-dev b/.claude/skills/halo-theme-dev new file mode 120000 index 0000000..2153e1a --- /dev/null +++ b/.claude/skills/halo-theme-dev @@ -0,0 +1 @@ +../../.agents/skills/halo-theme-dev \ No newline at end of file diff --git a/skills-lock.json b/skills-lock.json index 35b5794..417c7f4 100644 --- a/skills-lock.json +++ b/skills-lock.json @@ -4,7 +4,8 @@ "halo-theme-dev": { "source": "halo-dev/dev-skills", "sourceType": "github", - "computedHash": "f6b0a799298f6f729366fdad175662fa7386e615839ad4af807285954969a9f4" + "skillPath": "skills/halo-theme-dev/SKILL.md", + "computedHash": "3605e8cd3c7fa9390c5ef1037bf48a6392da5dc95b8ea2a08cbd4de92bf9f122" } } }