准备工作

Halo 的模板引擎为 Freemarker，建议在开发 Halo 的主题之前，先看一遍 Freemarker 的相关文档：http://freemarker.foofun.cn。

搭建开发环境

假设你已经在本地电脑配置好了 Java 运行环境。

Halo 的运行可参考上述 系统开发，或者直接下载打包好的程序启动，如下步骤：

  • 从 Github release 下载最新的 Jar 包。
  • 在终端中执行 java -jar halo-版本号.jar —spring.profiles.active=dev

启动完成之后，在电脑的用户目录即可看到 halo-dev 文件夹。

新建主题

  • 在 halo-dev/templates/themes 下新建一个文件夹，该文件夹就是你所新建的主题目录。
  • 使用你熟悉的编辑器打开你所新建的主题目录。

开发约定

  • 主题目录下必须存在 theme.yaml（主题描述文件），settings.yaml（主题配置文件），相关格式在后面会详细讲解。
  • 如果要开源到 Github 我们建议将仓库名设置为 halo-theme-主题名，并设置仓库的 topic 为 halo 和 halo-theme，这样可以方便使用者搜索。
  • 所有模板文件的后缀为 .ftl。
  • 主题目录需要以 screenshot 命名的预览图片，以供后台展示。
  • 如果是移植的其它主题，请在说明文档（如README）中注明原主题地址以及作者，以保证对原作者的尊重。

开发样板

为了让开发者更快速的上手主题的开发，我们提供了一个简单的开发样板以供参考。

仓库地址：https://github.com/halo-dev/halo-theme-quick-starter

目录结构

为了让开发更加规范，我们推荐使用以下的目录构建。

  1. ├── module                      // 公共模板目录
  2. │   ├── comment.ftl             // 比如：评论模板
  3. │   ├── layout.ftl              // 比如：布局模板
  4. ├── source                      // 静态资源目录
  5. │   ├── css                     // 样式目录
  6. │   ├── images                  // 图片目录
  7. │   ├── js                      // JS 脚本目录
  8. │   └── plugins                 // 前端库目录
  9. ├── index.ftl                   // 首页
  10. ├── post.ftl                    // 文章页
  11. ├── sheet.ftl                   // 自定义页面
  12. ├── sheet_xxx.ftl               // 自定义模板，如：sheet_search.ftl、sheet_author.ftl。在后台新建自定义页面可选择。
  13. ├── archives.ftl                // 归档页
  14. ├── categories.ftl              // 分类目录页
  15. ├── category.ftl                // 单个分类的所属文章页
  16. ├── tags.ftl                    // 标签页面
  17. ├── tag.ftl                     // 单个标签的所属文章页
  18. ├── search.ftl                  // 搜索结果页
  19. ├── links.ftl                   // 内置页面：友情链接
  20. ├── photos.ftl                  // 内置页面：图库
  21. ├── journals.ftl                // 内置页面：日志
  22. ├── 404.ftl                     // 404 页
  23. ├── 500.ftl                     // 500 页
  24. ├── README.md                   // README，一般用于主题介绍或说明
  25. ├── screenshot.png              // 主题预览图
  26. ├── settings.yaml               // 主题选项配置文件
  27. └── theme.yaml                  // 主题描述文件