Ryan Wang
6f1cede536
Replace the placeholder README with a full Chinese README for the Halo + Astro theme starter, adding rationale, architecture, dev/build instructions, directory layout, and usage notes. Also apply minor formatting/whitespace cleanups: adjust .vscode/settings.json formatting, collapse attributes on the category list div in src/pages/categories.astro, and remove an extra blank line in src/pages/category.astro. These are documentation and formatting changes only — no functional behavior changes.
122 lines
7.0 KiB
Markdown
122 lines
7.0 KiB
Markdown
# Theme Astro Starter
|
||
|
||
面向 [Halo](https://www.halo.run/) 的主题脚手架：以 **Astro** 作为预渲染框架，将组件与页面编译为干净的 HTML，交由 **Thymeleaf** 在运行时完成数据渲染。
|
||
|
||
官方主题开发指南：<https://docs.halo.run/developer-guide/theme/prepare>
|
||
|
||
## 为什么选择 Astro？
|
||
|
||
Halo 主题采用 Thymeleaf 纯后端渲染方案，传统上只能在 HTML 文件里直接写 Thymeleaf 语法。这对简单主题足够用，但若需要 Vue / React 组件或复杂的前端交互，就会很局限。
|
||
|
||
Astro 的特点恰好弥补了这一短板：
|
||
|
||
- **输出干净的 HTML**：Astro 不同于 SPA 框架，其默认产物是纯 HTML 文件，而不是 JS 包。Thymeleaf 的属性（`th:text`、`th:if`、`th:replace` 等）会作为普通 HTML 属性原样保留，两者互不干扰。
|
||
- **Island 架构**：仅在真正需要交互的地方注入客户端 JS（Vue / React 组件），其余部分零 JS 开销。
|
||
- **组件化开发体验**：通过 Astro 组件的 `slot` 与 `props` 在 **编译阶段** 组织布局与复用，最终产物是 Thymeleaf 可直接使用的 HTML 模板。
|
||
|
||
## 何时选择此 Starter？
|
||
|
||
| 场景 | 推荐 |
|
||
| ------------------------------------------------------- | ----------------------------------------------------------------------------- |
|
||
| 主题有较多前端交互，希望用 Vue / React 编写 Island 组件 | **本 Starter** |
|
||
| 主题以静态展示为主，前端交互需求较少 | [halo-dev/theme-vite-starter](https://github.com/halo-dev/theme-vite-starter) |
|
||
|
||
## 技术栈
|
||
|
||
| 类别 | 说明 |
|
||
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| 运行时 | Halo 使用 **Thymeleaf** 渲染主题；模板变量与 Finder API 随 Halo 版本演进，请以[官方文档](https://docs.halo.run/developer-guide/theme/prepare)为准 |
|
||
| 预渲染 | **Astro**，将 `src/` 下的页面与组件编译为 `templates/` 下的纯 HTML |
|
||
| UI 框架 | **Vue 3**（通过 `@astrojs/vue` 集成，用于编写 Island 组件） |
|
||
| 语言 | TypeScript（Astro 组件 frontmatter 支持） |
|
||
| 包管理 | **pnpm** |
|
||
|
||
## 核心概念：Astro 编译期 vs Thymeleaf 运行期
|
||
|
||
理解这两个阶段的边界是使用本 Starter 的关键：
|
||
|
||
```
|
||
开发时 构建后 Halo 运行时
|
||
───────────────────────────── ────────────────────── ──────────────────────────
|
||
src/pages/index.astro → templates/index.html → Thymeleaf 注入数据渲染
|
||
Astro 组件 / slot / props 干净的 HTML + th:text / th:if 生效
|
||
Vue Island 组件 Thymeleaf 属性原样 客户端 JS 激活 Island
|
||
```
|
||
|
||
**重要限制**：
|
||
|
||
- `slot`、`props` 是 Astro **编译期**的概念，Thymeleaf 运行时感知不到它们，也无法向 Astro 组件传递动态数据。
|
||
- 在 Astro 组件中可以直接写 `th:text`、`th:if`、`th:replace` 等 Thymeleaf 属性——Astro 会将其视为普通 HTML 属性原样输出，Thymeleaf 在运行时才会处理它们。
|
||
- Vue / React Island 组件（`client:*`）的数据来源是客户端（例如调用 Halo API），无法直接使用 Thymeleaf 的服务端变量。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
.
|
||
├── src/
|
||
│ ├── pages/ # Astro 页面（编译为 templates/ 下的 HTML）
|
||
│ │ ├── index.astro
|
||
│ │ ├── post.astro
|
||
│ │ ├── category.astro
|
||
│ │ └── ...
|
||
│ ├── layouts/
|
||
│ │ └── Layout.astro # 全局布局组件
|
||
│ ├── components/
|
||
│ │ ├── Header.astro
|
||
│ │ ├── Footer.astro
|
||
│ │ ├── ThemeSwitcher.vue # Vue Island 示例
|
||
│ │ └── ...
|
||
│ └── styles/ # 全局样式
|
||
├── public/ # 原样复制到 templates/：静态资源或纯 Thymeleaf 模板均可放此处
|
||
│ └── fragments/ # 纯 Thymeleaf 片段示例（不经 Astro 编译，直接输出）
|
||
├── templates/ # Astro 构建产物（Halo 实际读取的模板目录）
|
||
├── theme.yaml # 主题元数据（必填）
|
||
├── settings.yaml # 控制台主题设置表单（可选）
|
||
├── astro.config.mjs
|
||
└── package.json
|
||
```
|
||
|
||
> **`templates/` 是构建产物**，不要直接在此目录手动修改；请修改 `src/` 后重新构建。
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
git clone https://github.com/halo-sigs/theme-astro-starter.git ~/halo2-dev/themes/astro-starter
|
||
cd ~/halo2-dev/themes/astro-starter
|
||
pnpm install
|
||
pnpm dev
|
||
```
|
||
|
||
`pnpm dev` 会启动 Astro 开发服务器并监听 `src/` 变更，实时重新生成 `templates/`。
|
||
|
||
将主题目录链接或复制到 Halo 的 `themes/astro-starter/` 后，在控制台安装并启用主题即可预览。建议同时关闭 Thymeleaf 缓存以便热更新调试：
|
||
|
||
```yaml
|
||
# application.yaml
|
||
spring:
|
||
thymeleaf:
|
||
cache: false
|
||
```
|
||
|
||
或通过环境变量：`SPRING_THYMELEAF_CACHE=false`
|
||
|
||
## 构建
|
||
|
||
```bash
|
||
pnpm build
|
||
```
|
||
|
||
执行 Astro 构建，将 `src/` 编译输出到 `templates/`。构建完成后可将主题目录（含 `templates/`、`theme.yaml`、`settings.yaml` 等）打包为 ZIP 上传到 Halo 控制台，或使用 [`@halo-dev/theme-package-cli`](https://github.com/halo-dev/theme-package-cli) 完成打包。
|
||
|
||
## 其他脚本
|
||
|
||
| 命令 | 作用 |
|
||
| ------------- | ----------------------- |
|
||
| `pnpm format` | Prettier 格式化所有文件 |
|
||
|
||
## 注意事项
|
||
|
||
- Astro 配置中 `base` 需与 `theme.yaml` 的 `metadata.name` 保持一致（当前为 `astro-starter`），这决定了静态资源的引用路径。
|
||
- `public/` 目录不仅可以存放图片、字体等静态资源，也可以存放**纯 Thymeleaf 模板**（例如 `public/fragments/post-list.html`）。这些文件会被 Astro 原样复制到 `templates/` 对应路径，不经过任何编译处理，适合编写不需要 Astro 组件化的 Thymeleaf 片段。
|
||
- Vue Island 组件可通过 Halo 提供的 [API Client](https://www.npmjs.com/package/@halo-dev/api-client) 在客户端获取数据。
|