准备工作

此文档将讲解 Halo 2.0 主题开发的基本流程，从创建主题项目到最终预览主题效果。

搭建开发环境

Halo 在本地开发环境的运行可参考开发环境运行，或者使用 Docker 运行。

启用主题实时更新

为了保证在开发时，主题代码可以实时生效，需要注意以下事项：

使用 Halo 源码运行时，需要在配置文件中包含如下配置：
```
spring:
  thymeleaf:
    cache: false
```
使用 Docker 运行时，需要添加 SPRING_THYMELEAF_CACHE=false 的环境变量。

新建一个主题

Halo 的主题存放于工作目录的 themes 目录下，即 ~/halo2-dev/themes，在该目录下新建一个文件夹，例如 theme-foo。当前一个最小可被系统加载的主题必须在主题根目录下包含 theme.yaml 配置文件。

theme.yaml

apiVersion: theme.halo.run/v1alpha1
kind: Theme
metadata:
  # 此字段的值需要和主题文件夹名称一致，否则可能导致部分资源无法正常加载。
  name: theme-foo
spec:
  displayName: 示例主题
  author:
    name: Halo
    website: https://www.halo.run
  description: 一个示例主题
  logo: https://www.halo.run/logo
  homepage: https://github.com/halo-sigs/theme-foo
  repo: https://github.com/halo-sigs/theme-foo.git
  issues: https://github.com/halo-sigs/theme-foo/issues
  settingName: "theme-foo-setting"
  configMapName: "theme-foo-configMap"
  version: 1.0.0
  requires: 2.0.0
  license:
    - name: "GPL-3.0"
      url: "https://github.com/halo-sigs/theme-foo/blob/main/LICENSE"

查看主题配置文档

主题的配置文件详细文档请参考配置文件。

查看主题目录结构

通过模板创建

目前 Halo 为了让开发者能够尽快搭建主题项目，提供了一些初始模板，开发者可以根据实际需要选择使用。

halo-dev/theme-vite-starter - 面向大多数新主题的推荐模板，在 src 中开发并由 Vite 生成 Halo 使用的 templates 目录，详细用法请参考使用 Vite 开发主题。
halo-dev/theme-starter - 不使用前端构建工具的基础 Thymeleaf 主题模板。
halo-sigs/theme-astro-starter - 使用 Astro 预渲染，适合需要 Vue、React Island 或复杂前端交互的主题。

从模板仓库创建主题

以上 GitHub 都被设置为了模板仓库（Template repository），点击仓库主页的 Use this template 按钮即可通过此模板创建一个新的仓库。

创建新的主题仓库并克隆到本地开发环境之后，需要确保主题文件夹名称和 theme.yaml 中的 metadata.name 字段一致，否则可能导致部分资源无法正常加载。

创建第一个页面模板

Halo 使用 Thymeleaf 作为后端模板引擎，后缀为 .html，与单纯编写 HTML 一致。在 Halo 的主题中，主题的模板文件存放于 templates 目录下，例如 ~/halo2-dev/themes/theme-foo/templates。为了此文档方便演示，我们先在 templates 创建一个首页的模板文件 index.html：

templates/index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title th:text="${site.title}"></title>
  </head>
  <body>
    <h1>Hello World!</h1>
    <ul>
      <li th:each="post : ${posts.items}">
        <a th:href="@{${post.status.permalink}}" th:text="${post.spec.title}"></a>
      </li>
    </ul>
  </body>
</html>

安装主题

目前我们已经创建好了主题的项目，但并不会直接被 Halo 识别和加载，请按照以下的步骤安装和启用主题：

访问 Console 管理界面，进入主题管理页面。
点击右上角 切换主题 按钮，在选择主题弹窗中切换到 未安装 页面。
找到我们刚刚创建的主题，点击安装即可。
选择刚刚安装的主题，点击右上角的 启用 按钮。

此时 Halo 就已经成功加载并使用了该主题。然后我们访问首页 http://localhost:8090 就可以看到我们刚刚编写的 index.html 模板渲染后的页面了。

准备工作#

#搭建开发环境

#新建一个主题

#通过模板创建