feat: 初始化 Halo 暗色模式插件

- Halo Plugin 后端（Java/Gradle），含 DarkModePlugin 主类和测试 - Vue 3 + TypeScript 前端 UI，包含主题切换组件和设置页面 - 暗色模式 CSS 变量和覆盖样式（布局/编辑器/表单/滚动条等） - 设计文档和调查文档 - Halo 插件/主题开发 Agent Skills Co-Authored-By: Claude <noreply@anthropic.com>
2026-08-06 21:03:00 +08:00
commit edbf78f236
115 changed files with 14745 additions and 0 deletions
@@ -0,0 +1,69 @@
+# 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.