theme-vite-starter

KO | EN

gitlite — search

#hacktoberfest #ai #typescript #llm #golang #go #android #machine-learning #docker #macos #nodejs #mcp #openai #open-source

theme-vite-starter

(★ 13)

一个集成了 Vite 的主题快速开始模板。

theme-vite-starter Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Theme Vite Starter

面向 [Halo](https://www.halo.run/) 的主题脚手架：在 `src/` 中编写模板与前端资源，经构建生成 Halo 实际读取的 `templates/` 目录。

官方主题开发指南：<https://docs.halo.run/developer-guide/theme/prepare>

## 技术栈

| 类别     | 说明                                                                                                                                                                                                  |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 运行时   | Halo 使用 **Thymeleaf** 渲染主题；模板变量与 Finder API 随 Halo 版本演进，请以[官方文档](https://docs.halo.run/developer-guide/theme/prepare)为准。                                                   |
| 构建     | Vite，同时集成 [Vite Plus](https://viteplus.dev/)，集成格式化、Lint 等功能                                                                                                                            |
| 语言     | **TypeScript**（`tsc` 参与 `build` 脚本）                                                                                                                                                             |
| 主题插件 | [`@halo-dev/vite-plugin-halo-theme`](https://www.npmjs.com/package/@halo-dev/vite-plugin-halo-theme) — 源码见 [halo-sigs/vite-plugin-halo-theme](https://github.com/halo-sigs/vite-plugin-halo-theme) |
| 打包发布 | [`@halo-dev/theme-package-cli`](https://github.com/halo-dev/theme-package-cli) — 将主题打成 ZIP 供控制台上传                                                                                          |
| 包管理   | **pnpm**（版本见 `package.json` 的 `packageManager`）                                                                                                                                                 |

## 目录结构

- **`src/` 是源码目录**：在此维护 `.html` 页面与 `partials/` 片段、`css/`、`js/`（含 TS）等。插件在 **Vite 构建时** 处理 `<include>` / `<slot>` 等语法（与服务器上 **Thymeleaf 运行时** 互不替代，可同时使用）。
- **`templates/` 是构建产物**：Halo 只认主题根目录下的 `templates/`（内含页面 HTML 与 `templates/assets/` 等）。**不要**把 `src/` 当作 Halo 直接读取的路径；开发或发版前需执行构建，使 `templates/` 与当前源码一致。

```
.
├── src/                 # 源码：页面 HTML、partials、css、js
├── public/              # 可选；复制到 templates/assets/
├── templates/           # 构建生成
├── theme.yaml           # 主题元数据（必填）
├── settings.yaml        # 控制台主题设置表单（可选）
├── vite.config.ts
└── package.json
```

### `@halo-dev/vite-plugin-halo-theme`

1. **多页入口**：自动将 `src/` 下（除 `src/partials/` 外）的 `.html` 作为入口，输出到 `templates/` 下同名文件（例如 `src/index.html` → `templates/index.html`）。
2. **静态资源**：`src/` 中的 CSS/JS 由 Vite 打包进 `templates/assets/`；`public/` 中的文件会原样复制到 `templates/assets/`（不经打包）。
3. **模板复用**：支持构建期 `<include>`、`<slot>`，减轻纯 Thymeleaf 片段的重复书写。
4. **资源路径约定**：所有 HTML（含 `partials`）里引用静态资源时，路径按 **`src/` 根** 解析，而不是按当前文件所在子目录；说明见 [vite-plugin-halo-theme](https://github.com/halo-sigs/vite-plugin-halo-theme)。

## 开发

```bash
git clone git@github.com:halo-dev/theme-vite-starter.git ~/halo2-dev/themes/theme-vite-starter
cd ~/halo2-dev/themes/theme-vite-starter
pnpm install
pnpm dev
```

`pnpm dev` 等价于对主题执行 `vp build --watch`：修改 `src/` 后会持续重新生成 `templates/`。将主题目录链到或复制到 Halo 的 `themes/<metadata.name>/` 后，在控制台安装并启用主题即可预览。

开发 Halo 端建议关闭 Thymeleaf 缓存（例如环境变量 `SPRING_THYMELEAF_CACHE=false` 或配置 `spring.thymeleaf.cache: false`），便于模板热更新调试。

## 构建与打包

```bash
pnpm build
```

该命令会执行 TypeScript 检查、`vp build` 生成 `templates/`，并调用 `theme-package` 生成可分发的 ZIP。默认会打包 `templates/`、`theme.yaml` / `settings.yaml` 等必要文件，详见 [theme-package-cli](https://github.com/halo-dev/theme-package-cli)。

仅需要产物目录、不需要 ZIP 时：

```bash
pnpm build-only
```

## 其他脚本

| 命令         | 作用                                     |
| ------------ | ---------------------------------------- |
| `pnpm check` | `vp check --fix`（执行格式化和代码检查） |

## Agent Skills

仓库在 `.agents/skills/` 下内置了 **Halo 主题开发** 相关的 Agent Skill（例如 `halo-theme-dev`），整理了 Thymeleaf 要点、Finder API、`theme.yaml` / `settings.yaml`、vite 插件用法等参考材料。若在 Cursor 等支持 Agent Skills 的环境里开发，启用后可让 AI 更贴合 Halo 主题的约定来辅助编写与修改主题。

theme-vite-starter

theme-vite-starter Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

theme-vite-starter

theme-vite-starter Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README