mirror of
https://github.com/halo-dev/docs.git
synced 2025-10-22 19:04:55 +00:00
first commit
This commit is contained in:
Ryan Wang
34
docs/developer-guide/core/code-style.md
Normal file
34
docs/developer-guide/core/code-style.md
Normal file
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: 代码风格
|
||||
description: 代码风格的相关配置说明
|
||||
published: true
|
||||
date: 2021-07-09T03:07:39.180Z
|
||||
tags:
|
||||
editor: markdown
|
||||
dateCreated: 2021-03-04T12:58:29.590Z
|
||||
---
|
||||
|
||||
Halo 添加了 checkstyle 插件，来保证每位提交者代码的风格保持一致，减少无效代码的修改。本篇文章主要讲解如何在 IDEA 中添加 CheckStyle 插件，并引入项目所提供的 checkstyle.xml 配置。
|
||||
|
||||
## 安装 CheckStyle-IDEA
|
||||
|
||||
- 进入 IDEA 插件市场。
|
||||
- 搜索 CheckStyle-IDEA，点击安装即可。
|
||||
|
||||
## 配置 CheckStyle
|
||||
|
||||
- 进入 CheckStyle 配置（File | Settings | Other Settings | Checkstyle）。
|
||||
- 在配置文件中点击添加按钮，配置描述可随便填写（建议 Halo Checks），选择 ./config/checkstyle/checkstyle.xml，点击下一步和完成；
|
||||
- 勾选刚刚创建的配置文件。
|
||||
|
||||
## 配置 Editor
|
||||
|
||||
- 进入编辑器配置（File | Settings | Editor | Code Style）
|
||||
|
||||
- 导入 checkstyle.xm 配置：
|
||||
|
||||
|
||||
|
||||
- 选择 `./config/checkstyle/checkstyle.xml` 配置文件，点击确定即可。
|
||||
|
||||
至此，有关代码风格检查工具和格式化配置已经完成。
|
||||
148
docs/developer-guide/core/prepare.md
Normal file
148
docs/developer-guide/core/prepare.md
Normal file
@@ -0,0 +1,148 @@
|
||||
---
|
||||
title: 相关说明
|
||||
description: 开发环境的一些说明
|
||||
published: true
|
||||
date: 2021-07-09T03:07:37.190Z
|
||||
tags:
|
||||
editor: markdown
|
||||
dateCreated: 2021-03-04T12:56:25.883Z
|
||||
---
|
||||
|
||||
## 所需要的环境
|
||||
|
||||
1. IDE：[IntelliJ IDEA](https://www.jetbrains.com/idea/download/) 或者 [STS](https://spring.io/tools)（Spring Tools Suite）
|
||||
2. 工具：[Gradle](https://gradle.org/)，[Lombok](https://projectlombok.org/) 插件
|
||||
3. JDK：`11+`
|
||||
|
||||
> 推荐 IntelliJ IDEA 社区版（开源免费）https://github.com/JetBrains/intellij-community
|
||||
|
||||
|
||||
`Halo` 项目使用了 `Lombok`，运行 `Halo` 之前请检查 `IDE` 是否已经安装好了 `Lombok` 插件。
|
||||
|
||||
如果使用的 `IDE` 是 `IntelliJ IDEA`，请在设置中启用 `Build, Execution, Deployment/Annotation Processors` 的 `Enable annotation processing`。
|
||||
|
||||
如果仍然因为 `Lombok` 报错，请更新 `IntelliJ IDEA` 至最新版。
|
||||
|
||||
## 克隆项目（Optional）
|
||||
|
||||
如果你已经 `fork` 了 [`Halo`](https://github.com/halo-dev/halo)，请将以下命令中的 `halo-dev` 替换为你的 `Github 用户名`。
|
||||
|
||||
```bash
|
||||
git clone https://github.com/halo-dev/halo
|
||||
|
||||
// 如果你在 Github 上已经添加了你的 ssh key，请使用以下命令进行 clone：
|
||||
git clone git@github.com:halo-dev/halo.git
|
||||
|
||||
git submodule init
|
||||
|
||||
git submodule update
|
||||
```
|
||||
|
||||
这里推荐使用第二种方式进行克隆，这样每次提交代码的时候，就不会提示登录 `Github` 了。
|
||||
|
||||
## 导入项目
|
||||
|
||||
导入项目的时候请选择 `Gradle 项目`进行导入。
|
||||
|
||||
> `IntelliJ IDEA` 在导入项目的时候请勾选 `auto import`，推荐使用 `gradle wrapper`。
|
||||
|
||||
## 运行方式
|
||||
|
||||
`Halo` 运行方式总体来讲有以下两种：
|
||||
|
||||
### 直接运行 `Application` 主类（配合 IDE 运行）
|
||||
|
||||
如果需要指定配置，请在 `Run/Debug Configuration` 内进行设置 `VM options`（这里推荐采用上文的[自定义配置](#%E8%87%AA%E5%AE%9A%E4%B9%89%E9%85%8D%E7%BD%AE)），例如：
|
||||
|
||||
```ini
|
||||
-Dspring.profiles.active=dev
|
||||
-Dhalo.auth-enabled=false
|
||||
-Dhalo.production-env=false
|
||||
```
|
||||
|
||||
### 采用 `gradle bootRun task` 运行（不需要 IDE）
|
||||
|
||||
在项目根目录下运行以下命令：
|
||||
|
||||
```bash
|
||||
# 类 Unix 用户
|
||||
./gradlew bootRun
|
||||
|
||||
# Windows 用户
|
||||
./gradlew.bat bootRun
|
||||
```
|
||||
|
||||
如果需要手动指定配置，可添加 `--args` 参数（这里推荐采用上文的[自定义配置](#%E8%87%AA%E5%AE%9A%E4%B9%89%E9%85%8D%E7%BD%AE)），例如：
|
||||
|
||||
```bash
|
||||
# 类 Unix 用户
|
||||
./gradlew bootRun --args="--spring.profiles.active=dev --server.port=2333"
|
||||
|
||||
# Windows 用户
|
||||
./gradlew.bat bootRun --args="--spring.profiles.active=dev --server.port=2333"
|
||||
```
|
||||
|
||||
如果一切正常且没有额外指定配置，则可根据控制台的输出链接进行访问 `Halo`：
|
||||
|
||||
```java
|
||||
2019-06-06 16:20:52.285 INFO 1330 --- [ restartedMain] run.halo.app.listener.StartedListener : Halo started at http://127.0.0.1:8090
|
||||
2019-06-06 16:20:52.285 INFO 1330 --- [ restartedMain] run.halo.app.listener.StartedListener : Halo admin started at http://127.0.0.1:8090/admin
|
||||
2019-06-06 16:20:52.285 DEBUG 1330 --- [ restartedMain] run.halo.app.listener.StartedListener : Halo doc was enable at http://127.0.0.1:8090/swagger-ui.html # 仅在开发环境才会输出
|
||||
```
|
||||
|
||||
首次运行的时候，会跳转到博客安装页面，请大家耐心填写完毕，最后正式进入`开发之旅`。
|
||||
|
||||
这里推荐一个配置：
|
||||
|
||||
| key | value |
|
||||
| :----- | :------------ |
|
||||
| 用户名 | test |
|
||||
| 昵称 | test |
|
||||
| 邮箱 | test@test.com |
|
||||
| 密码 | opentest |
|
||||
|
||||
---
|
||||
|
||||
## 高级配置
|
||||
|
||||
### 调整启动参数（VMoptions）
|
||||
|
||||
运行命令中添加 `VM options`，例如：
|
||||
|
||||
```ini
|
||||
-Dspring.profiles.active=dev
|
||||
```
|
||||
|
||||
### 调整启动参数（args）
|
||||
|
||||
运行命令中添加参数，例如：
|
||||
|
||||
```ini
|
||||
--spring.profiles.active=dev
|
||||
```
|
||||
|
||||
`IDE` 一般都会提供一个 `Run/Debug 配置`，可以添加 `VM options` 和 `参数`。以上示例可以直接应用在以`命令运行`方式上。
|
||||
|
||||
### 启用自动构建（Build project automatically）
|
||||
|
||||
在开发环境下，修改代码之后，每次都需要重启应用，是一个非常耗时的操作。
|
||||
|
||||
有一个专门解决这个问题的工具，那就是 [JRebel](https://jrebel.com/)，但是它的费用实在是太昂贵，作为普通的开发者很难承受这笔费用（但**不推荐**使用破解版）。
|
||||
|
||||
于是 `Halo` 最后采用了 `Spring Boot` 官方推荐的 [Developer Tools](https://docs.spring.io/spring-boot/docs/current/reference/html/using-boot-devtools.html)。
|
||||
|
||||
这里以 `IntelliJ IDEA` 为例。
|
||||
|
||||
1. 进入 `Settings` (Preferences on macOS)。
|
||||
2. 打开 `Build, Execution, Deployment > Compiler`. 启用 `Build project automatically`。
|
||||
3. 点击 `应用`。
|
||||
4. 按 `Ctrl+Shift+A` (Cmd+Shift+A on macOS)快捷键，然后搜索 `Registry`。打开之后找到 `compiler.automake.allow.when.app.running`，并启用它 (IntelliJ IDEA 15 and newer)。
|
||||
|
||||
> 来源于 <https://zeroturnaround.com/software/jrebel/quickstart/intellij/enable-automatic-compilation-in-intellij-idea/>
|
||||
|
||||
|
||||
Developer Tools 原理
|
||||
|
||||
在保存代码的时候，`IDE` 会自动为我们编译代码，`Developer Tools` 检测到代码的 `class 文件`（只能检测 `classpath` 下的 `class 文件`）的变更，会自动重启项目。注意，这里的重启速度会有质的提升，具体原因是 `Spring Boot` 提供的 `restart 技术`提供了两个 `classloaders`：`base classloader` 和 `restart classloader`。当项目重启的时候 `restart classloader` 将会被抛弃，并重启创建一个，这比 `code starts`（冷启动）快很多。当然，肯定是比不上 `JRebel` 采用的 `Reload 技术`。
|
||||
|
||||
更多细节请查阅: [Automatic Restart](https://docs.spring.io/spring-boot/docs/current/reference/html/using-boot-devtools.html#using-boot-devtools-restart)
|
||||
46
docs/developer-guide/core/structure.md
Normal file
46
docs/developer-guide/core/structure.md
Normal file
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: 系统结构
|
||||
description: Halo 项目的构成
|
||||
published: true
|
||||
date: 2021-07-09T03:07:35.008Z
|
||||
tags:
|
||||
editor: markdown
|
||||
dateCreated: 2021-03-04T12:53:48.806Z
|
||||
---
|
||||
|
||||
[Halo](https://github.com/halo-dev/halo) 博客系统分为以下四个部分：
|
||||
|
||||
| 项目名称 | 简介 |
|
||||
| :------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- |
|
||||
| [halo](https://github.com/halo-dev/halo) | 提供整个系统的服务，采用 [Spring Boot](https://spring.io/) 开发 |
|
||||
| [halo-admin](https://github.com/halo-dev/halo-admin) | 负责后台管理的渲染，采用 [Vue](https://vuejs.org/) 开发，已集成在 Halo 运行包内，无需独立部署。 |
|
||||
| [halo-comment](https://github.com/halo-dev/halo-comment) | 评论插件，采用 [Vue](https://vuejs.org/) 开发，在主题中运行方式引入构建好的 `Javascript` 文件即可 |
|
||||
| [halo-theme-\*](https://github.com/halo-dev) | 主题项目集，采用 [Freemarker](https://freemarker.apache.org/) 模板引擎编写，需要包含一些特殊的配置才能够被 halo 所使用 |
|
||||
|
||||
## 自定义配置
|
||||
|
||||
> 为什么要提前讲自定义配置呢？是因为在这里让大家了解到 `Halo` 的`配置方式`，以及`配置优先级`，不至于未来运行项目的时候不知道如何优雅地修改配置。
|
||||
|
||||
`Halo` 配置目录优先级如下（从上到下优先级越来越小，上层的配置将会覆盖下层）:
|
||||
|
||||
- `Halo` 自定义配置
|
||||
- file:~/.halo/
|
||||
- file:~/.halo-dev/
|
||||
- `Spring Boot` 默认配置
|
||||
- file:./config/
|
||||
- file:./
|
||||
- classpath:/config/
|
||||
- classpath:/
|
||||
|
||||
> 参考: [Application Property Files](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html#boot-features-external-config-application-property-files)
|
||||
|
||||
在开发的时候，希望大家能够在 `~/halo-dev/application.yml` 中进行添加自定义配置。当然后面也会讲到如何用`运行参数` 和 `VM options` 进行控制配置，届时可根据具体情况进行选择。
|
||||
|
||||
|
||||
<article class="message is-warning">
|
||||
<div class="message-body">
|
||||
|
||||
开发的时候，我们不建议直接更改`项目源码`中的所包含的`配置文件`，包括 `application.yml`、`application-dev.yml`、`application-test.yml` 和 `application-user.yml`。
|
||||
|
||||
</div>
|
||||
</article>
|
||||
266
docs/developer-guide/theme/config-files.md
Normal file
266
docs/developer-guide/theme/config-files.md
Normal file
@@ -0,0 +1,266 @@
|
||||
---
|
||||
title: 配置文件
|
||||
description: 主题配置文件的说明
|
||||
published: true
|
||||
date: 2021-10-04T08:43:29.708Z
|
||||
tags:
|
||||
editor: markdown
|
||||
dateCreated: 2020-10-11T15:12:10.695Z
|
||||
---
|
||||
|
||||
> Halo 的主题模块使用 yaml 来对主题进行配置，`theme.yaml` 里面主要描述主题的名称，开发者的信息，开源地址等等。`settings.yaml` 包含了主题所有的配置选项，需要注意的是，这些选项仅仅是用于构建配置表单，并不起到对主题的配置作用。
|
||||
|
||||
## theme.yaml
|
||||
|
||||
```yaml
|
||||
id: 主题id，唯一，不能与其他主题一样。我们建议设置为 `作者名_主题名称`
|
||||
name: 主题名称
|
||||
author:
|
||||
name: 作者名称
|
||||
website: 作者网址
|
||||
description: 主题描述
|
||||
logo: 主题 Logo 地址
|
||||
website: 主题地址，可填写为 git 仓库地址
|
||||
repo: 主题 git 仓库地址，如有填写，后台可在线更新
|
||||
version: 版本号
|
||||
require: 最低支持的 Halo 版本，如：1.3.0，那么如果用户的版本为 1.3.0 以下，则无法安装
|
||||
|
||||
postMetaField: 文章自定义 meta 变量
|
||||
- meta_key
|
||||
|
||||
sheetMetaField:
|
||||
- meta_key 页面自定义 meta 变量
|
||||
```
|
||||
|
||||
示例：
|
||||
|
||||
```yaml
|
||||
id: caicai_anatole
|
||||
name: Anatole
|
||||
author:
|
||||
name: Caicai
|
||||
website: https://www.caicai.me
|
||||
description: A other Halo theme
|
||||
logo: https://avatars1.githubusercontent.com/u/1811819?s=460&v=4
|
||||
website: https://github.com/halo-dev/halo-theme-anatole
|
||||
repo: https://github.com/halo-dev/halo-theme-anatole
|
||||
version: 1.0.0
|
||||
require: 1.3.0
|
||||
postMetaField:
|
||||
- music_url # 假设在文章页面需要播放背景音乐，用户可以自己填写音乐地址。
|
||||
- download_url # 假设在文章页有一个下载按钮，那么用户也可以自己填写加载地址。
|
||||
|
||||
sheetMetaField:
|
||||
- music_url
|
||||
- download_url
|
||||
```
|
||||
|
||||
### 自定义 meta
|
||||
|
||||
这个为 1.2.0 引入的功能，用户可以在文章设置中设置自定义 meta，我们在 `theme.yaml` 中填写的 `postMetaField` 和 `sheetMetaField` 为预设项，当用户激活当前主题之后，在文章设置中即可看到预先设置好的项，然后填写对应的值即可。
|
||||
|
||||
关于这个 meta 变量如何调用的问题，会在后面的模板变量中阐述。
|
||||
|
||||
## settings.yaml
|
||||
|
||||
```yaml
|
||||
# Tab 节点
|
||||
group1:
|
||||
label: 第一个 Tab 名称
|
||||
# 表单项
|
||||
items:
|
||||
# 省略
|
||||
group2:
|
||||
label: 第二个 Tab 名称
|
||||
# 表单项
|
||||
items:
|
||||
# 省略
|
||||
```
|
||||
|
||||
## settings.yaml#items
|
||||
|
||||
> settings.yaml 的 items 下即为所有表单元素，所支持的表单元素如下
|
||||
|
||||
```yaml
|
||||
items:
|
||||
|
||||
# 普通文本框
|
||||
item1:
|
||||
name: item1 // 设置项的 name 值，在页面可通过 ${settings.item1!} 获取值。
|
||||
label: item1 // 表单项的 label
|
||||
type: text // 表单项类型：普通文本框
|
||||
placeholder: '' // 表单项的 placeholder，一般给用户提示
|
||||
default: '' // 表单项的默认值
|
||||
description: '' // 描述，一般用于说明该设置的具体用途
|
||||
|
||||
# 颜色选择框
|
||||
item1:
|
||||
name: item1 // 设置项的 name 值，在页面可通过 ${settings.item1!} 获取值。
|
||||
label: item1 // 表单项的 label
|
||||
type: color // 表单项类型：颜色选择框
|
||||
placeholder: '' // 表单项的 placeholder，一般给用户提示
|
||||
default: '' // 表单项的默认值
|
||||
description: '' // 描述，一般用于说明该设置的具体用途
|
||||
|
||||
# 附件选择框
|
||||
item1:
|
||||
name: item1 // 设置项的 name 值，在页面可通过 ${settings.item1!} 获取值。
|
||||
label: item1 // 表单项的 label
|
||||
type: attachment // 表单项类型：颜色选择框
|
||||
placeholder: '' // 表单项的 placeholder，一般给用户提示
|
||||
default: '' // 表单项的默认值
|
||||
description: '' // 描述，一般用于说明该设置的具体用途
|
||||
|
||||
# 多行文本框
|
||||
item2: // 设置项的 name 值，在页面可通过 ${settings.item2!} 获取值。
|
||||
name: item2
|
||||
label: item2 // 同上
|
||||
type: textarea // 表单项类型：多行文本框
|
||||
placeholder: '' // 同上
|
||||
default: '' // 同上
|
||||
description: '' // 描述，一般用于说明该设置的具体用途
|
||||
|
||||
# 单选框
|
||||
item3:
|
||||
name: item3 // 同上
|
||||
label: item3_label // 同上
|
||||
type: radio // 表单项类型：单选框
|
||||
data-type: bool // 数据类型：bool，string，long，double
|
||||
default: value1 // 同上
|
||||
description: '' // 描述，一般用于说明该设置的具体用途
|
||||
options: // 选项
|
||||
- value: value1 // 值
|
||||
label: label1 // 说明
|
||||
- value: value2
|
||||
label: label2
|
||||
|
||||
# 下拉框
|
||||
item4:
|
||||
name: item4 // 同上
|
||||
label: item4 // 同上
|
||||
type: select // 表单项类型：下拉框
|
||||
data-type: bool // 数据类型：bool，string，long，double
|
||||
default: value1 // 同上
|
||||
description: '' // 描述，一般用于说明该设置的具体用途
|
||||
options: // 选项
|
||||
- value: value1 // 值
|
||||
label: label1 // 说明
|
||||
- value: value2
|
||||
label: label2
|
||||
```
|
||||
|
||||
### 一个例子
|
||||
|
||||
假设我们的配置文件如下：
|
||||
|
||||
```yaml
|
||||
general:
|
||||
label: 基础设置
|
||||
items:
|
||||
index_title:
|
||||
name: index_title
|
||||
label: 首页标题
|
||||
type: text
|
||||
description: '注意：将覆盖博客标题'
|
||||
background_cover:
|
||||
name: background_cover
|
||||
label: 首页背景图
|
||||
type: attachment
|
||||
default: '/casper/assets/images/blog-cover.jpg'
|
||||
description: '设置首页的背景图，你可以点击右边的选择按钮选择图片。'
|
||||
background_color:
|
||||
name: background_color
|
||||
label: 首页背景颜色
|
||||
type: color
|
||||
default: '#fff'
|
||||
music_enabled:
|
||||
name: music_enabled
|
||||
label: 背景音乐
|
||||
type: radio
|
||||
data-type: bool
|
||||
default: false
|
||||
description: '是否开启背景音乐，默认为 false'
|
||||
options:
|
||||
- value: true
|
||||
label: 开启
|
||||
- value: false
|
||||
label: 关闭
|
||||
code_pretty:
|
||||
name: code_pretty
|
||||
label: 文章代码高亮主题
|
||||
type: select
|
||||
default: Default
|
||||
options:
|
||||
- value: Default
|
||||
label: Default
|
||||
- value: Coy
|
||||
label: Coy
|
||||
- value: Dark
|
||||
label: Dark
|
||||
- value: Okaidia
|
||||
label: Okaidia
|
||||
- value: Solarized Light
|
||||
label: Solarized Light
|
||||
- value: Tomorrow Night
|
||||
label: Tomorrow Night
|
||||
- value: Twilight
|
||||
label: Twilight
|
||||
```
|
||||
|
||||
页面取值：
|
||||
|
||||
```html
|
||||
// 获取首页标题
|
||||
|
||||
<#if settings.index_title?? && settings.index_title != ''>
|
||||
<h1>${settings.index_title!}</h1>
|
||||
</#if>
|
||||
```
|
||||
|
||||
```html
|
||||
// 获取背景图片
|
||||
|
||||
<#if settings.background_cover?? && settings.background_cover != ''>
|
||||
<img src="${settings.background_cover!}">
|
||||
</#if>
|
||||
```
|
||||
|
||||
```html
|
||||
// 获取背景颜色
|
||||
|
||||
<style>
|
||||
body{
|
||||
<#if settings.background_color?? && settings.background_color != ''>
|
||||
background-color: ${settings.background_color!}
|
||||
<#else>
|
||||
background-color: #fff
|
||||
</#if>
|
||||
}
|
||||
</style>
|
||||
|
||||
或者
|
||||
|
||||
<style>
|
||||
body{
|
||||
background-color: ${settings.background_color!'#fff'}
|
||||
}
|
||||
</style>
|
||||
|
||||
```
|
||||
|
||||
```html
|
||||
// 判断是否开启背景音乐
|
||||
|
||||
<#if settings.music_enabled!false>
|
||||
do something...
|
||||
</#if>
|
||||
```
|
||||
|
||||
```html
|
||||
// 获取代码高亮主题
|
||||
|
||||
<link rel="stylesheet" type="text/css" href="${theme_base!}/assets/prism/css/prism-${settings.code_pretty!'Default'}.css" />
|
||||
<script type="text/javascript" src="${theme_base!}/assets/prism/js/prism.js"></script>
|
||||
```
|
||||
|
||||
更多实例可参考：<https://github.com/halo-dev/halo-theme-material/blob/master/settings.yaml>。
|
||||
268
docs/developer-guide/theme/global-variable.md
Normal file
268
docs/developer-guide/theme/global-variable.md
Normal file
@@ -0,0 +1,268 @@
|
||||
---
|
||||
title: 全局变量
|
||||
description: 系统提供的一些全局变量
|
||||
published: true
|
||||
date: 2021-07-09T03:07:01.155Z
|
||||
tags:
|
||||
editor: markdown
|
||||
dateCreated: 2020-10-11T15:13:43.148Z
|
||||
---
|
||||
|
||||
## 博客地址
|
||||
|
||||
```
|
||||
${blog_url!}
|
||||
```
|
||||
|
||||
此变量与后台博客设置中的 `博客地址` 相对应。
|
||||
|
||||
|
||||
## 网站根路径
|
||||
|
||||
```
|
||||
${context!}
|
||||
```
|
||||
|
||||
需要注意的是，此变量和 `blog_url` 不同的是，这个变量有两种值，一种为相对路径形式，一种为绝对路径形式。
|
||||
|
||||
那么，当在后台博客设置中将 `全局绝对路径` 的选项打开时，`context` 变量值为 `${blog_url}/`，关闭时，`context` 的变量值为 `/`。
|
||||
|
||||
假设，我设置的 `博客地址` 为 `https://halo.run`，那么：
|
||||
|
||||
- 全局绝对路径为开启的状态下：https://halo.run/
|
||||
- 全局绝对路径为关闭的状态下：/
|
||||
|
||||
## 主题资源根路径
|
||||
|
||||
```
|
||||
${theme_base!}
|
||||
```
|
||||
|
||||
假设你的主题在 `~/halo-dev/templates/themes/anatole` 这个目录，那么 `theme_base` 为 `https://yourdomain/themes/anatole`
|
||||
|
||||
举个例子，你当前开发的主题为 `anatole`，当你要获取主题下 `css/style.css` 这个文件的路径，那么：
|
||||
|
||||
```
|
||||
${theme_base!}/css/style.css
|
||||
```
|
||||
|
||||
## 主题信息
|
||||
|
||||
主题名称：
|
||||
|
||||
```
|
||||
${theme.name!}
|
||||
```
|
||||
|
||||
主题 git 仓库地址：
|
||||
|
||||
```
|
||||
${theme.repo!}
|
||||
```
|
||||
|
||||
主题版本号：
|
||||
|
||||
```
|
||||
${theme.version!}
|
||||
```
|
||||
|
||||
## 博客标题
|
||||
|
||||
```
|
||||
${blog_title!}
|
||||
```
|
||||
|
||||
此变量与后台博客设置中的 `博客标题` 相对应。
|
||||
|
||||
## 博客 Logo
|
||||
|
||||
```
|
||||
${blog_logo!}
|
||||
```
|
||||
|
||||
此变量与后台博客设置中的 `Logo` 相对应。
|
||||
|
||||
## Halo 版本
|
||||
|
||||
```
|
||||
${version!}
|
||||
```
|
||||
|
||||
当前 Halo 的版本，如：1.3.0
|
||||
|
||||
## 博主信息
|
||||
|
||||
昵称：
|
||||
|
||||
```
|
||||
${user.nickname!}
|
||||
```
|
||||
|
||||
邮箱地址：
|
||||
|
||||
```
|
||||
${user.email!}
|
||||
```
|
||||
|
||||
描述：
|
||||
|
||||
```
|
||||
${user.description!}
|
||||
```
|
||||
|
||||
头像地址：
|
||||
|
||||
```
|
||||
${user.avatar!}
|
||||
```
|
||||
|
||||
上次登录时间：
|
||||
|
||||
```
|
||||
${user.expireTime!}
|
||||
```
|
||||
|
||||
## SEO 关键词
|
||||
|
||||
```
|
||||
${meta_keywords!}
|
||||
```
|
||||
|
||||
需要注意的是，虽然这个变量在任何页面都可以使用，但是其值可能在不同的页面是不一样的。会根据用户的设置，生成对应的值。
|
||||
|
||||
假设在文章页面：
|
||||
|
||||
- 如果用户为文章设置了标签，而没有设置 `自定义关键词`，系统会自动将标签设置为页面关键词。
|
||||
- 如果用户设置了 `自定义关键词`，那么则会取用户设置的值。
|
||||
|
||||
## SEO 描述
|
||||
|
||||
```
|
||||
${meta_description!}
|
||||
```
|
||||
|
||||
需要注意的是，虽然这个变量在任何页面都可以使用，但是其值可能在不同的页面是不一样的。会根据用户的设置，生成对应的值。
|
||||
|
||||
|
||||
## RSS 2.0 订阅地址
|
||||
|
||||
```
|
||||
${rss_url!}
|
||||
```
|
||||
|
||||
如：`https://yourdomain/rss.xml`
|
||||
|
||||
## Atom 格式的订阅地址
|
||||
|
||||
```
|
||||
${atom_url!}
|
||||
```
|
||||
|
||||
如：`https://yourdomain/atom.xml`
|
||||
|
||||
## Xml 格式的网站地图地址
|
||||
|
||||
```
|
||||
${sitemap_xml_url!}
|
||||
```
|
||||
|
||||
如：`https://yourdomain/sitemap.xml`
|
||||
|
||||
## HTML 格式的网站地图地址
|
||||
|
||||
```
|
||||
${sitemap_html_url!}
|
||||
```
|
||||
|
||||
如：`https://yourdomain/sitemap.html`
|
||||
|
||||
## 友情链接页面地址
|
||||
|
||||
```
|
||||
${links_url!}
|
||||
```
|
||||
|
||||
- **全局绝对路径为开启的状态下**：`https://yourdomain.com/{links_prefix}`
|
||||
- **全局绝对路径为关闭的状态下**：`/{links_prefix}`
|
||||
|
||||
`{links_prefix}` 是用户可设定的值，用户可以在后台修改 `友情链接` 的前缀，默认为 `links`。
|
||||
|
||||
## 图库页面地址
|
||||
|
||||
```
|
||||
${photos_url!}
|
||||
```
|
||||
|
||||
- **全局绝对路径为开启的状态下**：`https://yourdomain.com/{photos_prefix}`
|
||||
- **全局绝对路径为关闭的状态下**：`/{photos_prefix}`
|
||||
|
||||
`{photos_prefix}` 是用户可设定的值，用户可以在后台修改 `图库页面` 的前缀，默认为 `photos`。
|
||||
|
||||
## 日志页面地址
|
||||
|
||||
```
|
||||
${journals_url!}
|
||||
```
|
||||
|
||||
- **全局绝对路径为开启的状态下**：`https://yourdomain.com/{journals_prefix}`
|
||||
- **全局绝对路径为关闭的状态下**：`/{journals_prefix}`
|
||||
|
||||
`{journals_prefix}` 是用户可设定的值，用户可以在后台修改 `日志页面` 的前缀，默认为 `journals`。
|
||||
|
||||
## 文章归档页面地址
|
||||
|
||||
```
|
||||
${archives_url!}
|
||||
```
|
||||
|
||||
- **全局绝对路径为开启的状态下**：`https://yourdomain.com/{archives_prefix}`
|
||||
- **全局绝对路径为关闭的状态下**：`/{archives_prefix}`
|
||||
|
||||
`{archives_prefix}` 是用户可设定的值，用户可以在后台修改 `归档` 的前缀，默认为 `archives`。
|
||||
|
||||
## 分类列表页面地址
|
||||
|
||||
```
|
||||
${categories_url!}
|
||||
```
|
||||
|
||||
- **全局绝对路径为开启的状态下**：`https://yourdomain.com/{categories_prefix}`
|
||||
- **全局绝对路径为关闭的状态下**：`/{categories_prefix}`
|
||||
|
||||
`{categories_prefix}` 是用户可设定的值，用户可以在后台修改 `分类` 的前缀，默认为 `categories`。
|
||||
|
||||
## 标签列表页面地址
|
||||
|
||||
```
|
||||
${tags_url!}
|
||||
```
|
||||
|
||||
- **全局绝对路径为开启的状态下**：`https://yourdomain.com/{tags_prefix}`
|
||||
- **全局绝对路径为关闭的状态下**：`/{tags_prefix}`
|
||||
|
||||
`{tags_prefix}` 是用户可设定的值，用户可以在后台修改 `标签` 的前缀，默认为 `tags`。
|
||||
|
||||
## 页面判断
|
||||
|
||||
判断当前页面是否是特定的页面。
|
||||
|
||||
- **is_index**：首页
|
||||
- **is_post**：文章页
|
||||
- **is_sheet**：自定义页面
|
||||
- **is_archives**：归档页面
|
||||
- **is_categories**：分类列表页面
|
||||
- **is_category**：单个分类页面
|
||||
- **is_tags**：标签列表页面
|
||||
- **is_tag**：单个标签页面
|
||||
- **is_search**：搜索结果页面
|
||||
- **is_journals**：日志页面
|
||||
- **is_photos**：图库页面
|
||||
- **is_links**：友情链接页面
|
||||
|
||||
用法：
|
||||
|
||||
```html
|
||||
<#if is_index??>
|
||||
当前页面是首页
|
||||
</#if>
|
||||
```
|
||||
1378
docs/developer-guide/theme/page-variable.md
Normal file
1378
docs/developer-guide/theme/page-variable.md
Normal file
File diff suppressed because it is too large
Load Diff
81
docs/developer-guide/theme/prepare.md
Normal file
81
docs/developer-guide/theme/prepare.md
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
title: 准备工作
|
||||
description: 主题开发的环境搭建
|
||||
published: true
|
||||
date: 2021-07-09T03:06:48.338Z
|
||||
tags:
|
||||
editor: markdown
|
||||
dateCreated: 2020-10-11T02:39:41.346Z
|
||||
---
|
||||
|
||||
:::info
|
||||
Halo 的模板引擎为 Freemarker，建议在开发 Halo 的主题之前，先阅读一遍 Freemarker 的相关文档：<https://freemarker.apache.org>。
|
||||
:::
|
||||
|
||||
## 搭建开发环境
|
||||
|
||||
> 假设你已经在本地电脑配置好了 Java 开发环境。
|
||||
|
||||
Halo 的运行可参考上述 [系统开发](/developer-guide/core/prepare)，或者直接下载打包好的程序启动，如下步骤：
|
||||
|
||||
1. 从 [Github release](https://github.com/halo-dev/halo/releases) 或者 [https://dl.halo.run](https://dl.halo.run) 下载最新的运行包。
|
||||
2. 在终端中执行 `java -jar halo.jar --spring.profiles.active=dev`
|
||||
|
||||
启动完成之后，在电脑的用户目录即可看到 `halo-dev` 文件夹。
|
||||
|
||||
## 新建主题
|
||||
|
||||
1. 在 `~/halo-dev/templates/themes` 下新建一个文件夹，该文件夹就是你所新建的主题目录。
|
||||
2. 使用你熟悉的编辑器打开你所新建的主题目录，这里我们推荐使用 [Visual Studio Code](https://code.visualstudio.com)，并安装 [Freemarker](https://marketplace.visualstudio.com/items?itemName=dcortes92.FreeMarker) 扩展。
|
||||
|
||||
:::info
|
||||
我们同样为 Halo 主题开发了一个 `Visual Studio Code` Snippets 扩展，以简化一些操作，但目前处于 beta 状态，有需要的可以试试 [Halo theme develop Snippets](https://marketplace.visualstudio.com/items?itemName=halo-dev.halo-theme-dev-snippets-for-vs-code)。
|
||||
:::
|
||||
|
||||
## 开发约定
|
||||
|
||||
- 主题目录下必须存在 `theme.yaml（主题描述文件）`，`settings.yaml（主题配置文件）`，相关格式在后面会详细讲解。
|
||||
- 如果要开源到 Github 我们建议将仓库名设置为 `halo-theme-主题名`，并设置仓库的 `topic` 为 `halo` 和 `halo-theme`，这样可以方便使用者搜索。
|
||||
- 所有模板文件的后缀为 `.ftl`。
|
||||
- 主题目录需要以 `screenshot.png` 命名的预览图片，以供后台展示。
|
||||
|
||||
## 开发样板
|
||||
|
||||
> 为了让开发者更快速的上手主题的开发，我们提供了一个简单的开发样板以供参考。
|
||||
|
||||
仓库地址：<https://github.com/halo-dev/halo-theme-quick-starter>
|
||||
|
||||
## 目录结构
|
||||
|
||||
> 为了让开发更加规范，我们推荐使用以下的目录结构。
|
||||
|
||||
```
|
||||
├── module // 公共模板目录
|
||||
│ ├── comment.ftl // 比如：评论模板
|
||||
│ ├── layout.ftl // 比如：布局模板
|
||||
├── source // 静态资源目录
|
||||
│ ├── css // 样式目录
|
||||
│ ├── images // 图片目录
|
||||
│ ├── js // JS 脚本目录
|
||||
│ └── plugins // 前端库目录
|
||||
├── index.ftl // 首页
|
||||
├── post.ftl // 文章页
|
||||
├── post_xxx.ftl // 自定义文章模板，如：post_diary.ftl。可在后台发布文章时选择。
|
||||
├── sheet.ftl // 自定义页面
|
||||
├── sheet_xxx.ftl // 自定义模板，如：sheet_search.ftl、sheet_author.ftl。可在后台发布页面时选择。
|
||||
├── archives.ftl // 归档页
|
||||
├── categories.ftl // 分类目录页
|
||||
├── category.ftl // 单个分类的所属文章页
|
||||
├── tags.ftl // 标签页面
|
||||
├── tag.ftl // 单个标签的所属文章页
|
||||
├── search.ftl // 搜索结果页
|
||||
├── links.ftl // 内置页面：友情链接
|
||||
├── photos.ftl // 内置页面：图库
|
||||
├── journals.ftl // 内置页面：日志
|
||||
├── 404.ftl // 404 页
|
||||
├── 500.ftl // 500 页
|
||||
├── README.md // README，一般用于主题介绍或说明
|
||||
├── screenshot.png // 主题预览图
|
||||
├── settings.yaml // 主题选项配置文件
|
||||
└── theme.yaml // 主题描述文件
|
||||
```
|
||||
100
docs/developer-guide/theme/public-template-tag.md
Normal file
100
docs/developer-guide/theme/public-template-tag.md
Normal file
@@ -0,0 +1,100 @@
|
||||
---
|
||||
title: 公共宏模板
|
||||
description: 系统提供的一些宏模板
|
||||
published: true
|
||||
date: 2021-09-18T16:21:55.758Z
|
||||
tags:
|
||||
editor: markdown
|
||||
dateCreated: 2020-10-11T15:15:22.987Z
|
||||
---
|
||||
|
||||
> 为了减少重复代码，我们将某些常见的全局变量封装成了一个公共模板，我们只需要引入该模板，然后调用其中的宏模板即可。
|
||||
|
||||
## 公共 head 模板
|
||||
|
||||
> 需要注意的是，为了保证系统功能的完整性，我们强制要求在每个页面的 `<head>` 标签下必须包含此模板。
|
||||
|
||||
```html
|
||||
<@global.head />
|
||||
```
|
||||
|
||||
等同于：
|
||||
|
||||
```html
|
||||
<#if options.seo_spider_disabled!false>
|
||||
<meta name="robots" content="none">
|
||||
</#if>
|
||||
<meta name="generator" content="Halo ${version!}"/>
|
||||
<@global.favicon />
|
||||
<@global.custom_head />
|
||||
<@global.custom_content_head />
|
||||
```
|
||||
|
||||
## 公共底部
|
||||
|
||||
> 需要注意的是，为了保证系统功能的完整性，我们强制要求在每个页面的尾部必须包含此模板。
|
||||
|
||||
|
||||
```html
|
||||
<@global.footer />
|
||||
```
|
||||
|
||||
|
||||
等同于：
|
||||
|
||||
```html
|
||||
<@global.statistics />
|
||||
<@global.footer_info />
|
||||
````
|
||||
|
||||
## 相对时间
|
||||
|
||||
```html
|
||||
<@global.timeline datetime="时间" />
|
||||
|
||||
// 输出
|
||||
x 年前/x 个月前/x 天前/昨天/x 小时前/x 分钟前/x 秒前/刚刚
|
||||
```
|
||||
|
||||
|
||||
## 评论模块
|
||||
|
||||
```html
|
||||
<@global.comment target= type="" />
|
||||
```
|
||||
|
||||
等同于：
|
||||
|
||||
```html
|
||||
<#if !post.disallowComment!false>
|
||||
<script src="//cdn.jsdelivr.net/npm/vue@2.6.10/dist/vue.min.js"></script>
|
||||
<script src="${options.comment_internal_plugin_js!'//cdn.jsdelivr.net/npm/halo-comment@latest/dist/halo-comment.min.js'"></script>
|
||||
<halo-comment id="${post.id}" type="${type}"/>
|
||||
</#if>
|
||||
```
|
||||
|
||||
参数说明：
|
||||
|
||||
- target：post / sheet / journal 对象
|
||||
- type：评论类型，可为：post / sheet / journal
|
||||
|
||||
|
||||
例子：
|
||||
|
||||
在文章页面（post.ftl or post_xxx.ftl）：
|
||||
|
||||
```
|
||||
<@global.comment target=post type="post" />
|
||||
```
|
||||
|
||||
在自定义页面（sheet.ftl or post_sheet.ftl）：
|
||||
|
||||
```
|
||||
<@global.comment target=sheet type="sheet" />
|
||||
```
|
||||
|
||||
在日志页面（journals.ftl）：
|
||||
|
||||
```
|
||||
<@global.comment target=journal type="journal" />
|
||||
```
|
||||
2722
docs/developer-guide/theme/template-tag.md
Normal file
2722
docs/developer-guide/theme/template-tag.md
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user